Simple use of Swagger2

SpringBoot integrates Swagger2

When doing the post-development of some old projects, we will find that most companies do projects based on the development documents written by the project manager, and the programmers in the background develop the interface according to the interface documents. At this time, we will Some problems were found, because the code was changed after some small changes, but the document was not updated immediately, which caused it to not correspond to the code when reading the document later

Previously, the interface documents written by word were used. In most cases, there are several problems:

• Real-time update of interface documents and codes
• Specification Issues for Interface Documentation
• There are too many interface documents, which is inconvenient to manage

So Swagger's tool for automatically generating API documents appeared. Its advantages are:

• Swagger can automatically generate API documents and test functions online
• Swagger can be quickly integrated and used with SpringBoot

Swagger2 tutorial

1. Introduce dependencies in pom

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

2. Write the configuration class of Swagger2

/**
 * Swagger2 配置类
 * 在与spring boot 集成时，放在与application.java 同级的目录下
 * 通过@Configuration注解，让spring来加载该配置
 * 再通过@EnableSwagger2注解来启动Swagger2
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    

    /**
     * 创建API应用
     * appinfo()增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些接口暴露给Swagger来展现
     * 本例采用置顶扫描的包路径来定义指定要建立API的目录
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
    
    
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.Jason.chat"))
                .paths(PathSelectors.any()).build();
        return docket;
    }

    /**
     * 创建改API的基本信息（这些基本信息会展示在文档页面中）
     * 访问地址： http://项目实际地址/swagger-ui.html
     * @return
     */
    public ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，https://blog.csdn.net/weixin_43650254")
                .termsOfServiceUrl("https://blog.csdn.net/weixin_43650254")
                .contact("Jason")
                .version("1.0")
                .build();
    }
}

3. Use annotations to realize Swagger to automatically generate API documents

@Api: Used on a class to describe the function of the class.

@ApiOperation: annotations to add method descriptions to the API.

@ApiImplicitParams : Used on methods to contain a set of parameter descriptions.

@ApiImplicitParam: Used to annotate to add descriptions to method input parameters.

@ApiResponses: Used to represent a set of responses

@ApiResponse: Used in @ApiResponses, generally used to express a wrong response message

• code: number, such as 400

• message: information, such as "request parameters are not filled in"

• response: the class that threw the exception

@ApiModel: Describes the information of a Model (generally used when the request parameter cannot be described using the @ApiImplicitParam annotation)

• @ApiModelProperty: describes the properties of a model

Note: The parameter description of @ApiImplicitParam:

parameter	illustrate
paramType: specify where the parameter is placed	header: request parameters are placed in Request Header, use @RequestHeader to get query: request parameters are placed in request address, use @RequestParam to get path: (for restful interface) –> get request parameters: @PathVariable body: (not commonly used) form (uncommonly used)
name: parameter name
dataType: parameter type
required: Whether the parameter must be passed	true | false
value: Explain the meaning of the parameter
defaultValue: the default value of the parameter