1, Foreword

As the most popular Java web development scaffold, Spring Boot is used by more and more developers to build enterprise RESTFul API interfaces. These interfaces will serve not only the traditional web side (b/s), but also the mobile side. In the actual development process, these interfaces should also be provided to the development and testing for relevant white box testing, so there is bound to be the problem of how to share and update API development interface documents in multi person cooperation.

Integrating documents with Swagger has the following advantages:

• Rich functions: support multiple annotations, automatically generate interface documents, and test API interface functions on the interface;
• Update in time: spend a little time writing comments in the development process, you can update API documents in time, which saves you worry and effort;
• Simple integration: by adding pom dependencies and simple configuration, you can publish API interface documents and interfaces embedded in the application at the same time without deploying independent services.

Next, we use Spring Boot to integrate Swagger to realize the functions of online API documents. In this paper, we use SpringFox Swagger2, version 2.9.2 (the latest version is 3.0.0, but in my test, the swagger-ui.html page has not come out. In https://mvnrepository.com/ You can also see that 2.9.2 is the most used version at present)

2, Create Spring Boot project

The development tool I use is IDEA. I can quickly create a Spring Boot project through IDEA. When creating, just check the web dependency option. It doesn't matter if I don't check it. The configuration in pom.xml is the same later. Note that when creating a project, the project name should be lowercase.

Add two dependencies of Swagger

<!-- swagger -->
<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>

3, Add configuration class

Add a swagger configuration class, create a new config package under the project, and add a SwaggerConfig configuration class SwaggerConfig.java.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
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 createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("on-line API file")
                .description("This is a restful api document of demo")
                .version("1.0")
                .build();
    }

}

The above has completed the configuration of Swagger. Is it very simple and easy.

4, Create a test Controller to verify the configuration

Add a controller, create a new controller package under the project, and add a HelloController.java.

package com.louis.springboot.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

/* Class annotation */
@Api
@RestController
public class HelloController {

    /* Method annotation */
    @ApiOperation(value = "desc of method", notes = "")
    @GetMapping(value="/hello")
    public Object hello( @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) {
        return "Hello " + name + "!";
    }
}

5, Compile and run tests

Start the project, open the browser and visit: http://localhost:8080/swagger-ui.html to enter the swagger interface document interface.

It's convenient to manage the API interface and update the code in real time. You don't have to worry about writing interface documents.

Appendix: Swagger common notes

There are many strange problems in WEB project development.