Documenting your Spring Boot app with Swagger

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:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

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.

@Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(getApiInfo())
          .select()
          .apis(RequestHandlerSelectors.basePackage("eu.dreamix.team"))              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
    
	private ApiInfo getApiInfo() {
		return new ApiInfoBuilder().title("Homix Project")
				.description(
						"This API is about homix project. Which is internal project in Dreamix. The project stores information about team members")
				.version("1.0.0").build();
	}

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: https://localhost:8080/v2/api-docs

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

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

The result should look like this:

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.

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.

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.

public class TeamMember {
        @Id
        @GeneratedValue(strategy = GenerationType.IDENTITY)
        @ApiModelProperty(notes = "The database generated member ID")
        private final Long id;
        @NotNull
        @JsonProperty(required = true)
        @Column(name = "EMAIL")
        @ApiModelProperty(notes = "The email of a team member")
        private final String email;
        @NotNull
        @JsonProperty(required = true)
        @Column(name = "FIRST_NAME")
        @ApiModelProperty(notes = "The first name of a team member")
        private final String firstName;
        @NotNull
        @JsonProperty(required = true)
        @Column(name = "LAST_NAME")
        @ApiModelProperty(notes = "The photo URL of a team member")
        private final String lastName;
        @Column(name = "PHOTO_URL")
        private final String photoUrl;

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

@ApiResponses(
                value = {
                    @ApiResponse(code = 200, message = "Successfully retrieved list of team members"),
                    @ApiResponse(code = 201, message = "New member was successfully created"),
                    @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
                    @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
                    @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")        
                }
                )

The result is:

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