Swagger configuration and use tutorial

1. introduction.
In the process of project development, a good API development document is essential. The development document helps the communication between front and rear end users and reduces the communication cost. Due to some problems in the previous development document, such as too many interfaces, complex details, and the API interface can not be updated in real time, Swagger2 was born. It perfectly solves this problem. As a standard and complete framework, it can be used to generate Describe, invoke, and visualize RESTful style Web services.
2. use.
1. let's use springboot to use swagger. First, create a springboot project.

2. select the web module and test it in the browser later.

3. after completion, we need to introduce the dependency of swagger. Two dependencies are required here, one springfox-swagger2 and the other springfox-swagger-ui

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

4. after dependency import, we need to write a configuration class to enable Swagger2. Nothing can be written in the configuration class. The default or user-defined configuration can be used. Let's not write anything first. Let's look at the default situation first, and then customize the configuration.
Configuration class:

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

The two annotations here, one @Configuration, indicate that this is an annotation class, and the @EnableSwagger2 annotation indicates that Swagger2 is enabled. After that, let's start the test.
Enter the web address in the browser: http://localhost:8080/swagger-ui.html . Note that the swagger-ui HTML page, the default page in swagger, and the subsequent request interfaces are on this page.

You can click this interface to see that there are many request modes. When we use the restui request mode, there is only one mode. Let's write some interface tests.

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/test")
public class HelloController {

    @GetMapping("one")
     public String one(){
         return  "one";
     }

    @PostMapping("two")
    public String two(){
        return  "two";
    }

    @DeleteMapping("three")
    public String three(){
        return  "three";
    }

    @GetMapping("add/{a}/{b}")
    public int add(@PathVariable int a ,
                     @PathVariable int b){
        return  a+b;
    }
}

Note that the annotation here is @RestController.
We still open http://localhost:8080/swagger-ui.html

Click open.

Here are the four test interfaces we have written. Let's test the addition.



In this way, the interface test is successful.

3. custom configuration Swagger
In addition, let's customize the configuration of Swagger to make it more user-friendly.
Open the Swagger configuration class you just wrote. We haven't configured anything yet.

import com.google.common.base.Predicates;
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.service.ApiInfo;
import springfox.documentation.service.Contact;
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 webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                //Call the apiinfo method to create an apiinfo instance,
                // Inside is the information displayed on the document page
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }


    // api documentation details
    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("API Document interface test")    //title
                .description("This document describes interface test cases")  //describe
                .version("1.0")  //edition
                .contact(new Contact("java", "http://baidu.com", "123@qq.com"))
                .build();
    }
}

After writing these configurations, let's first look at the effect

In the configuration class, the corresponding position is configured to make the api document clearer.