Swagger for documenting your Spring Boot REST Api

 

What Is Swagger?

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

Swagger  is mostly used as an open source project for describing and documenting RESTful APIs.  Swagger-UI an another tool which provides the capability of displaying the REST Api documentation in the browser.  Besides rendering documentation, Swagger UI allows other API developers or consumers to interact with the API’s resources without having any of the implementation logic in place.

The more details can be found through following documentations.

https://swagger.io/docs/ 

http://springfox.github.io/springfox/docs/current/

 

Springfox for Swagger

The Swagger 2 specification, which is known as OpenAPI specification has several implementations. Currently, Springfox that has replaced Swagger-SpringMVC (Swagger 1.2 and older) is popular for Spring Boot applications.

What we are going to do?

This article will explain how the Swagger is integrated into the Spring Boot REST Api as a API documentation generator. So in order to proceed with this article, you need to have a Spring Boot based REST Api project.

 

Integrating Swagger for your Project

To bring it in, we need the following dependency declaration in our Maven POM. This includes two dependencies springfox-swagger2 and springfox-swagger-ui. 

 

Adding the following Swagger Configuration

 

@EnableSwagger2 

This will add the Swagger 2 support for the Spring REST Api project.

 

Advanced configuration with Docket

The Docket bean of your application can be configured to give you more control over the API documentation generation process.

Docket is a builder that provides default configuration of Swagger documentation. If you want a custom implementation, then you need to create a method in Swagger configuration class with return type Docket annotated with @Bean. (please refer the restApi() method of the above Swagger configuration class)

 

Filtering and Restricting Api Documentation with apis() and paths()

It is not always desirable to expose the documentation for your entire API. You can restrict Swagger’s response by passing parameters to the apis() and paths() methods of the Docket class. In this way, you can decide which part of the REST api needs to be exposed through documentation and which part need to be restricted from being generating Api documentation.

according to above configuration class, the REST Api documentation will be generated only for the controllers which are in the below package.

com.springbootdev.examples.swagger.controller

 

 

Configure Spring Security to allow the access of REST Api documentation with Swagger UI

 

The most of the Spring Security configuration will require the user authentication and authorization for accessing certain part of the application. It will restrict the user access of the certain part of the application (URLs)  if they are not explicitly excluded from checking the authentication and authorization. Therefore we need to exclude the URL that is used to access the Swagger based REST Api documentation from authentication and authorization security checking.  This can be done by adding the following configuration for your main Spring Security configuration file.

 

 

Rendering REST Api documentation with Swagger UI

Now our initial configuration is done with integrating Swagger for the Spring REST Api. Now it is the time to render the generated documentation with Swagger UI. You can follow the instructions given below.

  • build  and run the project. This can be done with following command.
   mvn spring-boot:run

(In your case, it can be accessed with http://localhost:8080/swagger-ui.html)

Then you will see the Swagger generated API documentation as follows.

Screen Shot 2018-05-11 at 10.32.56 PM.png

 

 

Swagger Annotations

@ApiOperation: Provides documentation support for REST web service method, for example what operation this method performs.

@ApiParam: Provides documentation support about parameter of REST web service method.

@Api: provides the support for documenting RestContoroller classes. Grouping the set of @ApiOperation endpoints.

@ApiModel: provides the support for documenting the DTO models.

 

Here are some real usages of some of the annotations described above.

 

 

Based on the above UserController, following documentation will be generated.

Screen Shot 2018-05-12 at 10.15.51 AM.png

 

 

Please refer the below DTO model (AddUserRequest.java).

 

 

The following documentation segment will be generated for the above mode.

Screen Shot 2018-05-12 at 10.20.25 AM.png

 

You find more annotation related to the Swagger REST API documentation in the official documentation.

http://springfox.github.io/springfox/docs/current/

 

Source Code

A sample Spring Boot REST Api project  (that is documented using Swagger) can be accessed through following GitHub Repository.

https://github.com/chathurangat/spring-boot-rest-swagger

 

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s