We connect Swagger module in Play Framework

Documenting Play Framework using Swagger

Original source for setting up the swagger module

The Play Framework is an MVC web framework for the Java and Scala programming languages ​​from a company previously called Typesafe, and now Lightbend.

site:

Play framework

article from Habr:

Impressions from working with Play! Framework 2.1 + Java

wiki

Play (framework)

programmer's notes

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

Swagger is a whole host of tools throughout the entire life cycle of an API development, from design and documentation, to testing and deployment.

site:

Swagger

articles from Habr:

Documenting # microservices

3 best tools for describing RESTful API

wiki:

Openapi

Swagger (software)

Moving away from the introduction, we can proceed to the installation of the API documentation, which is generated on the fly.

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

Swagger Module

The swagger-play2 module is required for automatic generation of API specifications .

Swagger ui

At the office. The Swagger.io website provides the Swagger UI , which accepts the Swagger json specification and generates a dynamic web interface for learning, experimenting and understanding the API.

Customize Play

And now, let's start integrating the swagger module. For testing, use the Play Framework version 2.6.3

1. Add the plugin as dependency to the build.sbt file

   
   

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

   
   
2. We connect the Swagger module in 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 specification.

Documenting the API

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

Sample code is described below. Add the following code to the controller class.

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

For each method that we need to add documentation, we need to define the following annotation.
The standard response class is already provided, here it is Response.class .

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

For each additional response that the API can return, you can add the following annotation.

 @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 specification by adding a route to the conf/routes configuration file conf/routes

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

Now, we can reach the Swagger specifications from /docs/swagger.json

Add Swagger UI to the Play Framework

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

In the config file route, add the following directorates

 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) 

In case you want to redirect to the Swagger specification by default in the application root, then add this route to the route config:

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

Update index.html to change the link 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, sbt and starts playframework , go to http://localhost:9000/docs/ to see the live Swagger UI running.

Good

• Using Swagger Special, it is very easy to effectively communicate with the API for anyone who is going to use the API.
• Automatic generation of client code from the Swagger specification has made consuming and testing the API very simple.

Still not good enough

There are several problems in Swagger UI.

• Sometimes you need to reload the page to make it work again.
• If there is no connection to the API service, the UI cannot explicitly say this.
• The API reference path prefix is ​​not currently processed in the Swagger UI.
• Swagger specification generation includes security configuration is not correctly implemented (not to the end).
• Perhaps you should use major versions of the Play Framework as there is backing in support for the latest versions.

Total

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

Swagger video connections can be viewed here .