Let’s Play! - My Play Framework Learning Journey (8) - Play Swagger Annotation

Swagger is “a powerful open source framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs.”. Using Swagger one can document and generate API specifications in Json and as a web UI. Swagger specifications are required by API related products like IBM API Connect to create service definitions.

One use of Swagger is to annotate your code and generate specifications based on the annotations. Swagger-Play does exactly this for Play Framework. The rest of this blog will cover this in details. Swagger can also be used to define API specifications and generate code stubs from the specification but that usage is not covered here.

Using Swagger-Play

To use Swagger-Play, follow the following steps:

  • Add Swagger-play dependency
libraryDependencies += "io.swagger" %% "swagger-play2" % "1.5.3"
  • Enable Swagger module in Play by adding the following to application.conf:
play.modules.enabled += "play.modules.swagger.SwaggerModule"
  • Optionally add more Swagger API information in application.conf. For example:
api.version = "v0.1.0"
swagger.api.info = {
  contact : "Charles Xu Cheng",
  description : "Demo REST APIs",
  title : "Demo REST APIs",
  termsOfService : "TODO"
  • Modify Play’s routes file to include the following:
# Swagger Json
GET     /swagger.json           controllers.ApiHelpController.getResources
# Swagger UI
GET     /docs/              controllers.Assets.at(path="/public/swagger-ui",file="index.html")
GET     /docs/swagger.json  controllers.ApiHelpController.getResources
GET     /docs/*file         controllers.Assets.at(path="/public/swagger-ui",file)
  • Use Swagger annotations such as @Api, @ApiModel, @ApiModelProperty and @ApiOperation at the respective classes. Swagger-Play will generate Swagger Json and UI based on those.

Example ApiModel type:

case class ConversionRequest(
  @ApiModelProperty(required = true, value = "desc") attr1: String,
  @ApiModelProperty(required = true, value = "desc") attr2: BigDecimal)

One thing to note is that Swagger-Play does not work with Play’s routing using Router classes.

Annotating Request Body

With @Api, @ApiModel, @ApiModelProperty and @ApiOperation, you can document most aspects of your APIs. However, when you pass in some objects in the request body as Json in Play, there is no method parameter variable for you to annotation with.

Luckily, Swagger provides an @ApiImplicitParams for this case.

@ApiImplicitParams(Array[ApiImplicitParam](new ApiImplicitParam(name = "body", value = "Conversion Request", required = true, dataType = "controllers.ConversionRequest", paramType="body")))

Place it before the controller method that takes input from request body.

Also take note of the syntax of specifying array of annotations in Scala in the above example, as the normal Java syntax does not work with Scala.

Additional References

Go Top
comments powered by Disqus