Documenting a Spring Boot CRUD RESTful API/Web Service with Swagger

Overview

In a previous article, which you can check here, we started the development of a simple users API using Spring boot. We recommend it to be read before continuing with this article.

Spring Boot is a powerful tool when creating a RESTful web service and Swagger is a powerful tool when documenting a RESTful web service, which can also be used for quick testing the API.

When building a back-end API layer, it’s necessary to also think about the users that’ll be interacting with the API, thus the point of documentation.

A good documentation should have a informative structure and should be easy to read. This article will focus on implementing and setting up Swagger to provide our service with such characteristics.

It is also possible to do the other way around, and create an API starting from an Open API specification. But we will cover that in another post.

Quick demo

An example of what we should aim to build is the Petstore that was generated using Swagger UI.

There are 3 endpoints group categories, each with a set of operations described in a simple and easy to understand way :

• pet
• store
• user

Also, we’re able to verify the flow of the API by going through the endpoints and this is essentially what we should aim to do with our implementation.

Getting started

Our first step should be adding the following Springfox implementations of Swagger to our maven pom.xml file in the API project folder.

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

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

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-data-rest</artifactId>
  <version>3.0.0-SNAPSHOT</version>
</dependency>

Configuring Swagger into our API

Coding-wise we should begin by creating a configuration class for Swagger and adding our Docket bean which will be the core of all implementation specifics.

We’re implementing WebMvcConfigurer in our class to eventually configure the resource handlers that’ll be added through the Swagger UI dependency.

src/main/java/com/usersapi/swagger/SpringFoxConfiguration.java

@Configuration
@EnableSwagger2WebMvc
@EnableWebMvc
public class SpringFoxConfiguration implements WebMvcConfigurer {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.usersapi"))
                .paths(PathSelectors.any())
                .build();
    }
}

Implementing resource handlers

In our SpringFoxConfiguration class, we need to implement resource handlers with the @Override annotation to specify that this should override any standard configuration from Spring :

src/main/java/com/usersapi/swagger/SpringFoxConfiguration.java

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
      .addResourceLocations("classpath:/META-INF/resources/");
 
    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/");
} 

Adding custom information to our user interface

Adding the apiInfo method to our Docket bean should provide us with the possibility of creating a customInfo class with our custom info :

src/main/java/com/usersapi/swagger/SpringFoxConfiguration.java

@Bean
public Docket productApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.usersapi"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(customInfo());
}

private ApiInfo customInfo() {

    ApiInfo customInfo = new ApiInfo(
            "Users API",
            "CodeFiction Project",
            "2.0",
            "Terms of service",
            new Contact("Gabriel Pulga", "www.codefiction.net", "[email protected]"),
            "API license",
            "API license URL",
            Collections.emptyList());

    return customInfo;
}

If we visit our localhost page at http://localhost:8080/swagger-ui.html, we’re able to verify that Swagger is already up and running with each of our endpoints listed in the web page.

Endpoint documentation

For each endpoint controller we’ll need to describe its functionality through the @Api and @ApiOperation annotations, so for instance, our DeleteUserController should be :

src/main/java/com/usersapi/endpoints/delete/DeleteUserController.java

@RestController
@RequestMapping("/users/{id}")
@Api(tags = "Delete an existing user with the DELETE method")
public class DeleteUserController {

    @Autowired
    DeleteUserService service;

    @DeleteMapping
    @ResponseStatus(HttpStatus.NO_CONTENT)
    @ApiOperation(value = "Execute DELETE method")
    public void deleteUser_whenDeleteUser(@PathVariable Long id) {
        service.deleteUser(id);
    }
}

Endnotes

Throughout this tutorial you learned how to implement Swagger in a Spring Boot RESTful API and describe each of your endpoints functionalities by creating custom descriptions with the purpose of making a friendlier user interface.

Next possible steps for developing our API will be :

• Unit testing our endpoints controllers and services with JUnit and Mockito.
• Integration testing our whole API.

Source code

Available in our github page.

Thanks for reading !! Feel free to leave any comment.