Documenting your Spring Boot app with Swagger

Documenting your Spring Boot app with Swagger

July 17, 2018
frontpage, Java
No Comment

Documenting your Spring Boot app with Swagger

Why is API documentation important?

What is Swagger?

Swagger is one of the most popular tools for automatically generating REST API documentation easily. In this article we will use a Springfox-based implementation of Swagger.

How to set up Swagger in your app

Тhe first step when integrating Swagger in your application is to add the springfox dependency to your pom.xml project file:

Springfox is the actual tool which is used for generating documentation for JSON-based Spring APIs.

You will have to add Swagger configuration to your Spring boot application. In the configuration class add @EnableSwagger2 and this will enable swagger2 for apps. In the class we add a bean which returns a Docket. It will build our swagger.

We can use a configuration method to customize the swagger. The select() method, created by our configuration, returns an ApiSelectorBuilder, which also provides to us methods for customization.
In the apis() method we can provide the base package. If we add this, swagger will generate specification only for classes whose packages start with this package.

It’s the same with paths() methods filtering our specification which follows the convention for our paths provided in paths method. Here we can provide regex for filtering.

Also you can add some additional information about application in apiInfo() method. For that purpose springfox provides ApiInfoBuilder, so that you can add title, description, version and etc.

When you run our application, specification will be generated. You can check it here: http://localhost:8080/v2/api-docs

spring boot app with swagger

There you can see the JSON file explains our REST API. This documentation is very hard for reading, so spring fox provides Springfox’s Swagger UI, which makes that pretty easy. For UI we will add dependency in the pom.xml

Now we can test it on: http://localhost:8080/swagger-ui.html#/

The result should look like this:

spring boot app with swagger

On the top of the page you can see information for the API. Underneath you can see the rest of the services which we provide. The services are grouped by controllers and you can easily see type of service. You can open each service and you will see more information.

spring boot app with swagger

You can ask for an example from the service. Also you can see value for you request. If you click on this section, swagger will automatically populate the request section. In the bottom you can see list of HTTP status codes. In the model section you can see more information for requested body.

spring boot app with swagger

Additional customization for swagger?

You can add more information about model and service description as well.
In the model with annotation @ApiModelProperty(notes = “Write description here”) you can add notes for every property in your model.

With @ApiResponses annotation you can show more information for status codes which application returns:

The result is:
spring boot app with swagger

I hope you find the information useful. If you like what you have just read or have any questions, hit the comment button below.

Stoyan Ivanov

Java & Oracle Developer at Dreamix

More Posts - Website

Do you want more great blogs like this?

Subscribe for Dreamix Blog now!