Several pain points of handwritten Api documents:

1. When a document needs to be updated, it needs to send another copy to the front end, that is, the document update communication is not timely.
2. Ambiguous interface return result
3. You can't test the interface directly online. You usually need to use tools, such as postman
4. Too many interface documents, not easy to manage

Swagger is to solve this problem. Of course, it can't be said that swagger must be perfect. Of course, it also has disadvantages. The most obvious is that the code is relatively mobile.

For others, if you want to know about Swagger, you can go to the official website of Swagger, and you can directly use Swagger editor to write interface documents. Of course, we're going to talk about how spring boot integrates Swagger 2 to generate interface documents directly.

Introducing dependency

<!-- swagger2 Interface document-->
		<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>

Swagger configuration class

In fact, this configuration class only needs to know what can be configured. After all, this thing will not be moved after it is configured once. In particular, the path of the api file, which is the controller package, is configured. Otherwise, the generated document cannot scan the interface.

package com.gpdi.lxq.eladmin.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @description: Interface document
 * @author: Lxq
 * @date: 2020/1/19 9:25
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.gpdi.lxq.eladmin.rest"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxxxxxxxxxxxxx platform APIs")
                .description("xxxxxxxxxxxxxx APIs")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact(new Contact("developer", "#", ""))
                .version("1.0")
                .build();
    }
}

Swagger2 documentation

Start the SpringBoot project, visit http://localhost:19099/el-admin/swagger-ui.htm

Swagger notes

Through annotation, swagger indicates that the interface will generate documents, including interface name, request method, parameter, return information, etc.

• @Api: decorate the whole class to describe the function of Controller
• @ApiOperation: a method, or an interface, that describes a class
• @ApiParam: single parameter description
• @ApiModel: receiving parameters with objects
• @ApiProperty: a field describing an object when receiving parameters with the object
• @ApiResponse: HTTP response one of the descriptions
• @ApiResponses: overall description of HTTP response
• @ApiIgnore: use this annotation to ignore this API
• @ApiError: information returned when an error occurs
• @ApiImplicitParam: a request parameter
• @Apiimplicit params: multiple request parameters