Why use Swagger to automatically generate interface documents

Swagger is a complete framework. In the project, it is used to automatically generate the corresponding interface documents, and can directly test the interface on the visualization tool. I will sort out swagger2 0 + version and swagger3 Differences and deployment methods of version 0

1. Project integration Swagger

The premise of this integration is that you can use Swagger to integrate with the spring Maven, which is based on the following two methods

1.1 Maven integrated Swagger

Code slice in pom file

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

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

1.2 Gradle integrated Swagger

Code slice in Gradle file

    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'

2. Start configuring Swagger

After importing the required jar packages through the above two methods, we can start to configure Swagger. First, we configure a SwaggerConfig class to start Swagger

1. Create a swaggerconfig java

SwaggerConfig.java code slice

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.CacheControl;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

/**
 * @description: Swagger2 to configure
 * @date: 2020-11-19 12:25  
 **/
//Represents a configuration class
@Configuration 
//Turn on Swagger
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
	//Because Swagger automatically generates documents by invading code, a switch can be set here to
	//Turn off swagger. On the production environment Enabled = false to close
    @Value("${swagger.enabled:false}")
    private boolean swaggerabled;
    @Value("${swagger.api.info.title}")
    private String title;
    @Value("${swagger.api.info.description}")
    private String description;
    @Value("${swagger.api.info.version}")
    private String version;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2) //Swagger version: if the imported swagger dependency is 3.0, the Type here is OAS_ thirty
                .enable(swaggerabled)
                .apiInfo(getApiInfo()).groupName("XXX-api")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.XXX.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
        		//Title of Api document
                .title(title)
                //Description of Api document
                .description(description)
                //Version number of Api document
                .version(version)
                .termsOfServiceUrl("")
                .build();
    }
}

3. Handle the entity class User of the input parameter

The code slice in the User file

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.hibernate.validator.constraints.Length;
import javax.validation.constraints.NotEmpty;
import java.util.Date;

/**
 * @description:
 * @author: 
 * @date: 
 **/
@Data
@ApiModel( description= "Requested user entity class")
public class User {
    protected String id;
    /** User number [32,0] Not NULL */
	@ApiModelProperty(hidden = true)
    protected String department;
   }

Add @ ApiModel annotation to the entity class. Description is the description of the entity
You can see that in the attribute, we use the @ ApiModelProperty annotation and the attribute hidden=true, so we can't see the attribute in the request body in the automatically generated interface document

In this way, we have completed the first step of configuring Swagger. Next, we process the Controller that needs to automatically generate interface documents

4. Processing Controller

Code slice in Controller

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

/**
 * @description:
 * @author: 
 **/
@RestController
@Api(tags = "Swagger test")
@RequestMapping("/test")
public class UserController {

    @ApiOperation(value = "Get user entity class",notes = "according to ID Get user entity class")
    @ApiImplicitParam(name = "user",value = "User entity class",dataType = "",required = true)
    @PostMapping("/getUserById")
    public User getUserById(@RequestBody User user)
    {
        return userService.getUserById(user);
    }
}

Adding the @ Api annotation to the Controller above means that a module can be understood as a method in the interface document @ Api, which will not be introduced here

On the getUserById method in UserController, we can see some corresponding relationships between some annotations of Swagger and the automatically generated interface document

5. Modify the Springboot startup class

We need to add the annotation of Swagger in the Application of Springboot startup class

Code slice in Application file

@SpringBootApplication
@EnableSwagger2
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

6. Access SwaggerUi automatically generated by annotation

After adding the @ EnableSwagger2 annotation in Applicaiton above, we start the Spriingboot project. Remember to add the springboot web dependency first to make it a web project. After starting, we visit the address
http://localhost:8080/swagger-ui.html is enough. Here I start the springboot server locally Port is the default 8080
The effect is as follows

7. Update the second interface later

The interface of automatically generating documents displayed in the second interface will be updated later