Home Java Plugging the Swaggermodule into the Play Framework

Plugging the Swaggermodule into the Play Framework

by admin
Documenting Play Frameworkusing Swagger

Original source on swagger module setup

Play Framework – is a MVC web framework for Java and Scala programming languages from a company formerly called Typesafe, now called Lightbend.

website :

Play Framework

Habra article :

Impressions of Play! Framework 2.1 + Java

wiki

Play (framework)

programmer’s notes

Play Framework – everything you wanted to know about it, but for some reason were afraid to ask

Swagger – is a whole host of tools, throughout the API development lifecycle, from design and documentation, to testing and deployment.

website :

Swagger

articles from Habra :

Documenting #microservices
The 3 best tools for describing RESTful APIs

wiki:

OpenAPI
Swagger (software)

Moving away from the introduction, we can start installing the API documentation, which is generated on the fly.

For the demonstration we will use the play framework version 2 : Play 2

Swagger Module

For automatic generation of the API specification you will need the module swagger-play2

Swagger UI

On the official website Swagger.io provides Swagger UI which takes the Swagger specification in json format and generates a dynamic web interface for learning, experimenting and understanding the API.

Setting up Play

Now, let’s start integrating the swagger module.For testing we use Play Framework version 2.6.3

  1. Let’s add plugin as an assembly file build.sbt

    libraryDependencies += "io.swagger" %% "swagger-play2" % "1.6.0"

  2. Connecting Swagger module in the conf/application.conf

play.modules.enabled += "play.modules.swagger.SwaggerModule"api.version = "v1" //Specify the api version.

More settings can be added to the conf/application.conf for autogenerating additional fields in the Swagger spec.

Documenting API

  • Swagger annotations available in package io.swagger.annotations
  • Swagger annotations are used to document the API in Controller classes.

An example code is described below.Add the following code to the controller class.

@Api(value = "Example Controller", produces = "application/json")

For each method to which we want to add documentation, we have to define the following annotation.
The standard answer class is already provided, here it is Response.class

@ApiOperation(value = "Get API", notes = "Get list of id values.", response = Response.class)

The following annotation can be added for each additional response that the API can return.

@ApiResponses({@ApiResponse(code = 403, message = "Invalid Authorization", response = ErrorStatus.class), @ApiResponse(code = 500, message = "Internal Server Error", response = ErrorStatus.class) })

Parameters in controller methods can be added as follows :

@ApiOperation(value = "Get User", response = User.class)public Promise<Result> getUser(@ApiParam(value = "User Id", name = "userId") String userId){User user = getUser(userId);return ok(user);}

Routes

We can access the autogenerated Swagger spec by adding a route to the configuration file conf/routes

GET /docs/swagger.json controllers.ApiHelpController.getResources

Now, we can access the Swagger specification from /docs/swagger.json

Adding Swagger UIto the Play Framework

Since the Swagger UI is just a dynamic frontend with HTML/JS, it can be provided directly via Nginx or httpd
Alternatively, we can also provide the Swagger UI from the play framework.
This also solves the problem with any CORS error that might occur when the API and Swagger UI are on different domains.
Copy distribution Swagger UI to /public/swagger-ui Into your Play project.

In the route config file, add the following directives

GET /docs/ controllers.Assets.at(path="/public/swagger-ui", file="index.html")GET /docs/swagger.json controllers.ApiHelpController.getResourcesGET /docs/*file controllers.Assets.at(path="/public/swagger-ui", file)

In case you want in the root of the application / make a redirect to the default Swagger specification, then add this route to the routes config :

GET / controllers.Default.redirect(to = "/docs/")

Update index.html to change the reference to the Swagger specification.

With

var url = window.location.search.match(/url=([^]+)/);if (url url.length > 1) {url = decodeURIComponent(url[1]);}else {url = "http://petstore.swagger.io/v2/swagger.json";}

On

var url = window.location.search.match(/url=([^]+)/);if (url url.length > 1) {url = decodeURIComponent(url[1]);} else {url = "swagger.json";}

Explore API

Once upon a time, sbt will compile and run playframework , go to http://localhost:9000/docs/ to see live working Swagger UI

Well

  • Using Swagger Spec, made very simple to effectively communicate with the API for anyone who is going to use the API.
  • Automatic generation of client code from the Swagger spec made API consumption and testing very easy.

Still not good enough

There are several problems in Swagger UI.

  • Sometimes you need to reload the page to get it working again.
  • If there is no connection to API service, UI can’t tell about it explicitly.
  • The API link path prefix is not currently handled in Swagger UI.
  • Swagger specification generation includes security configuration is not correctly implemented.
  • Maybe you should use major versions of Play Framework as there is a backlog in support for the latest versions.

Total

Total Swagger Spec/UI is a great tool, for describing and providing access to any API.

A video of the Swagger connection can be seen here

You may also like