I introduced OpenAPI (Swagger) to Spring Boot (gradle) and tried various settings

Introduction

Last year, I created Personal development application called Settlement-kun, but I didn't create the backend API specification, so let's quickly create it using OpenAPI (Swagger). I came to use it. I will touch on the introduction method at that time and the settings that I personally care about.

environment

• Java 11.0.3 (Amazon Corretto)
• gradle 6.0.1
• SpringBoot 2.2.3
• Seisankun-api https://github.com/nooboolean/seisankun_api
• SwaggerUI 2.9.2

What is OpenAPI (Swagger)?

The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services.

(Translation) The OpenAPI Specification is a specification of machine-readable interface files for describing, generating, consuming, and visualizing RESTful web services.

From wikipedia

So, to put it simply, OpenAPI is an interface for creating specifications for RESTful Web services (API, etc.). Originally the name was Swagger, but it seems that the name has changed to Open API because it was donated to OAI (Open API Initiative) established by Microsoft/Google/IBM on December 31, 2015. SmartBear Software, the creator of Swagger, also participated in OAI, and it seems that it was donated. However, since OpenAPI has not yet become popular as a name, there are still people and articles that call it Swagger.

Introduced OpenAPI (Swagger) to Spring Boot

There are several ways to introduce OpenAPI into Spring Boot. Among them, this time we will introduce using SpringFox. SpringFox is a library of Spring Framework that can create OpenAPI-based specification documents. https://github.com/springfox/springfox

Defined in gradle

Describe the following description in build.gradle.

build.gradle

~abridgement~
dependencies {
        compile("io.springfox:springfox-swagger2:${Version of your choice}")
        compile("io.springfox:springfox-swagger-ui:${Version of your choice}")
~abridgement~
}

For $ {your favorite version}, specify the version you want to use. The version that can be specified in the link below and its usage rate are described.

springfox-swagger2 springfox-swagger-ui

Create Configure class

Use the AutoConfigure function of SpringBoot to load the settings. Create the following Configure class.

SwaggerConf.java

package com.dededesignworkshop.seisankun_api.config;

import org.springframework.context.annotation.Bean;
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 SwaggerConf {

    @Bean
    public Docket swaggerPlugin() {
        return new Docket(DocumentationType.SWAGGER_2) // SWAGGER_12, SWAGGER_2, SWAGGER_I have a WEB but I don't really know which one is better
                .select() //Generate ApiSelectorBuilder
                .apis(RequestHandlerSelectors.any()) //Set the RequestHandler that is the target of the document
                .paths(PathSelectors.regex("/v1.*")) //Set the target path of the document
                .build();
    }

}

A class called Docket is defined as a bean. The official document is here, so please take a look at the other setting items as well.

Browser display

When you access the path of /swagger-ui.html, the following will be displayed.

Various settings

There is no problem with the above Bean definition as the minimum setting, but there are many other customizations, so I tried it.

API basic information setting

You can set basic API information with apiInfo () of Docket. This is the red frame part of the image.

Add the following to the Configure class above.

SwaggerConf.java

~abridgement~

@Configuration
@EnableSwagger2
public class SwaggerConf {

    @Bean
    public Docket swaggerPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("/v1.*"))
                .build()
                .apiInfo(getApiInfo()); //API basic information setting with ApiInfo type
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("Seisankun-api")
                .description("Travel split calculation app\"Liquidation\"API")
                .version("1.0.0")
                .contact(new Contact("nooboolean","webSiteUrl","email"))
                .build();
    }
}

The official document is here, so please see other setting items as well.

Advanced settings for each endpoint

By defining a bean that returns the UiConfiguration class in UiConfigurationBuilder, detailed settings for each endpoint can be made. You can set the following screens.

Add the following to the Configure class above.

SwaggerConf.java

~abridgement~

@Configuration
@EnableSwagger2
public class SwaggerConf {

~abridgement~

    @Bean
    public UiConfiguration swaggerUiConf() {
        return UiConfigurationBuilder.builder()
                .displayRequestDuration(true)
                .defaultModelExpandDepth(3)
                .defaultModelRendering(ModelRendering.EXAMPLE)
                .filter(true)
                .operationsSorter(OperationsSorter.METHOD)
                .validatorUrl("")
                .docExpansion(DocExpansion.LIST)
                .build();
    }
}

Details of the items set this time.

The official document is here, so please take a look at the other setting items as well.

Setting a description for each endpoint

You can write a description of what role each endpoint plays. This is possible by annotating the method of each endpoint with ApiOperation.

UserController.java

    @ApiOperation(value = "Refer to the user list associated with travel", notes = "Refers to the user list associated with the travel ID specified in the parameter")
    public List<User> findByTravelId(@PathVariable("travel_id") Integer travel_id) {
        return this.userService.findByTravelId(travel_id);
    }

The display results are as follows.

There seems to be more customization, so I will add it each time I customize it additionally! !!