Auto document your Spring Boot REST API with Springfox

Documentation is usually a pain for the developpers. If you use Spring Boot, there is a way to automatically generate the documentation, from you code, with no effort at all.
Interested ? Let's do it now.

Prerequisites

• A GIT client 
• JDK >= 1.8
• maven

Get the sample code

In a previous article, I built a REST API with Spring Boot to access a mongo database. You can start from this code. 

See the article here :

https://ben-touron.blogspot.com/2019/03/deploy-fullstack-app-in-cloud-using-gcp_2.html

Customize the code

Add the dependencies in your pom.xml

In order to work, you need some extra libraries. In the dependencies bloc, add the following sub-blocs :

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-data-rest</artifactId>
    <version>2.9.2</version>
</dependency>

• swagger2 is necessary to generate the swagger file from your classes. It's a big JSON file, containing the documentation. 

• swagger-ui allows you to generate the GUI of your documentation. Unlike the swagger file, it's human readable.
• data-rest is a complement to generate the documentation for a REST repository, which is our case here

Downgrade the Spring Boot version

Ooops. At this time, with springfox 2.9.2, you cannot use Spring boot 2 together with Springfox Data Rest. There is an issue in their github. 

Modify in the version sub bloc of the parent bloc :

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.19.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

If you have a clue to make it work with Spring Boot 2, please leave a comment !

Add the swagger config class

Now, to make the Spring Boot magic happen, you need to add a class in src/main/java/com/example/demo

Call it SwaggerConfig.java with the folloging content :

import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

Enable swagger on the application class

Edit the DemoApplication.java in the following :

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Import;
import springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
@Import(SpringDataRestConfiguration.class)
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

And you're done !

Build and run your application

As in the previous article build and run the app :

$ mvn clean install

$ java -jar  java -jar demo-0.0.1-SNAPSHOT.war

 Browse your documentation

• To get the swagger file (JSON) :

http://localhost:8080/v2/api-docs

•  To get the swagger-ui (HTML) :

http://localhost:8080/swagger-ui.html

• The full code can ge cloned from github :

git clone https://github.com/benoittouron/autodocumented-rest-api.git