Spring boot integrates swagger3, detailed explanation of swagger annotations

1. Introducing dependencies

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-boot-starter</artifactId>
      <version>3.0.0</version>
</dependency>

2. Configuration file

spring:  
  mvc:
    # swagger配置
    pathmatch:
      matching-strategy: ant_path_matcher

Three, swagger configuration class

@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {         return new ApiInfoBuilder()                 .title("Swagger3 Interface Documentation")                 .description("Document Description")                 .contact(new Contact("Name", "URL", "Email"))                 .version( "1.0")                 .build();     } }








 

Fourth, use (common annotations)

on the controller class

@Api(tags = "User query interface", description = "Add, delete, modify, query user list, password initialization")
on the controller method

@ApiOperation("query user list")
test: open http://localhost:9000/swagger-ui/index.html
 

1. @Api() : used on the requested class, indicating the description of the class, and also representing that this class is a swagger2 resource

parameter:

tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

2. @ApiOperation() : used for methods, indicating that an http request accesses the operation of the method

parameter:

value="方法的用途和作用"    
notes="方法的注意事项和备注"    
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"} 
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

3. @ApiModel() : used to respond to entity classes, used to illustrate the role of entities

parameter:

description="描述实体的作用"  

4. @ApiModelProperty : Used on attributes to describe the attributes of entity classes

parameter:

value="用户名"  描述参数的意义
name="name"    参数的变量名
required=true     参数是否必选

5. @ApiImplicitParams : Used in the request method, including multiple @ApiImplicitParams

6. @ApiImplicitParam : Used for methods, representing individual request parameters

parameter:

name="参数ming" 
value="参数说明" 
dataType="数据类型" 
paramType="query" 表示参数放在哪里
    · header 请求参数的获取：@RequestHeader
    · query   请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用） 
defaultValue="参数的默认值"
required="true" 表示参数是否必须传

7. @ApiParam() : Used for methods, parameters, and field descriptions to indicate the requirements and descriptions for parameters

parameter:

name="参数名称"
value="参数的简要说明"
defaultValue="参数默认值"
required="true" 表示属性是否必填，默认为false

8. @ApiResponses : Used in the request method, different responses are indicated according to the response code

One @ApiResponses contains multiple @ApiResponse

9. @ApiResponse : Used in the request method to indicate different responses

Parameters :

code="404"    表示响应码(int型)，可自定义
message="状态码对应的响应信息"   

10. @ApiIgnore() : Used on classes or methods, not displayed on the page

11. @Profile({"dev", "test"}) : Used on configuration classes, indicating that it is only useful for development and test environments