SpringDoc注解解析

一、什么是SpringDoc

SpringDoc注解的使用,它是基于OpenAPI 3和Swagger 3的现代化解决方案,相较于旧版的Swagger2(SpringFox),SpringDoc提供了更简洁、更直观的注解方式。
SpringDoc注解解析_第1张图片

二、SpringDoc的注解分类

2.1 作用于类的注解

1. @Tag

用于说明或定义的标签。也可以作用于方法上
部分参数:

name:名称
description:描述

@Tag(name = "用户接口", description = "用户管理相关接口")
@RestController
@RequestMapping("/users")
public class UserController {

}

2. @Hidden

某个元素(API操作、实体类属性等)是否在 API 文档中隐藏。当我们想要隐藏某些不必要的信息时,可以使用@Parameter(hidden = true)、@Operation(hidden = true)或者@Hidden注解。

3. @ApiResponse

API 的响应信息。也可以作用于方法上,一般常用于方法上
部分参数:

responseCode:响应的 HTTP 状态码
description:响应信息的描述
content:响应的内容

@ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "404", description = "查询失败")
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
    // ...
}

4. @Schema

用于描述实体类属性的描述、示例、验证规则等,比如 POJO 类及属性。

部分参数:

name:名称
title:标题
description:描述
example:示例值
required:是否为必须
format:属性的格式。如 @Schema(format = “email”)
maxLength 、 minLength:指定字符串属性的最大长度和最小长度
maximum 、 minimum:指定数值属性的最大值和最小值
pattern:指定属性的正则表达式模式
type: 数据类型(integer,long,float,double,string,byte,binary,
boolean,date,dateTime,password),必须是字符串。
如 @Schema=(type=“integer”)
implementation :具体的实现类,可以是类本身,也可以是父类或实现的接口。

@Tag(name = "用户", description = "用户实体类")
@Data
public class User {
    @Schema(name = "用户id", type = "long")
    private Long id;
    @Schema(name = "用户名", type = "long")
    private String name;
    @Schema(name = "密码", type = "password", minLength = "6", maxLength = "20")
    private String password;
}

2.2 作用于方法上

1. @Operation

描述 API 操作的元数据信息。常用于 controller 的方法上

部分参数:

summary:简短描述
description :更详细的描述
hidden:是否隐藏
tags:标签,用于分组API
operationId:操作的唯一标识符,建议使用唯一且具有描述性的名称
parameters:指定相关的请求参数,使用 @Parameter 注解来定义参数的详细属性。
requestBody:指定请求的内容,使用 @RequestBody 注解來指定请求的类型。
responses:指定操作的返回内容,使用 @ApiResponse 注解定义返回值的详细属性。

@Operation(
  summary = "操作摘要",
  description = "操作的详细描述",
  operationId = "operationId",
  tags = "tag1",
  parameters = {
    @Parameter(name = "param1", description = "参数1", required = true),
    @Parameter(name = "param2", description = "参数2", required = false)
  },
  requestBody = @RequestBody(
    description = "请求描述",
    required = true,
    content = @Content(
      mediaType = "application/json",
      schema = @Schema(implementation = RequestBodyModel.class)
    )
  ),
  responses = {
    @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseModel.class))),
    @ApiResponse(responseCode = "400", description = "错误", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponseModel.class)))
  }
)
// @Tag(name = "标签1")
// @ApiResponses(value = {
//  @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ResponseModel.class))),
//  @ApiResponse(responseCode = "400", description = "錯誤", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponseModel.class)))
//})
public void Operation() {
  // 逻辑
}
 

2. @Parameter

用于描述 API 操作中的参数

部分参数:

name : 指定的参数名
in:参数来源,可选 query、header、path 或 cookie,默认为空,表示忽略
ParameterIn.QUERY 请求参数
ParameterIn.PATH 路径参数
ParameterIn.HEADER header参数
ParameterIn.COOKIE cookie 参数
description:参数描述
required:是否必填,默认为 false
schema :参数的数据类型。如 schema = @Schema(type = “string”)

@Operation(summary = "根据用户名查询用户列表")
@GetMapping("/query/{username}")
public List<User> queryUserByName(@Parameter(name = "username", in = ParameterIn.PATH,
    description = "用户名",required = true) @PathVariable("username") String userName) {
    return new ArrayList<>();
}

3. @Parameters

包含多个 @Parameter 注解,指定多个参数。

@Parameters({
  @Parameter(
    name = "param1",
    description = "description",
    required = true,
    in = ParameterIn.PATH,
    schema = @Schema(type = "string")
  ),
  @Parameter(
    name = "param2",
    description = "description",
    required = true,
    in = ParameterIn.QUERY,
    schema = @Schema(type = "integer")
  )
})

4. @RequestBody @Content

内容注解。

部分参数:

mediaType:内容的类型。比如:application/json
schema:内容的模型定义,使用 @Schema 注解指定模型的相关信息。

@Operation(
  requestBody = @RequestBody(
    description = "请求描述",
    required = true,
    content = @Content(
      mediaType = "application/json",
      schema = @Schema(implementation = RequestBodyModel.class)
    )
  )
)
public void Operation() {
  // 逻辑
}

三、场景配置

3.1 类及 pojo 上

@Tag(name = "用户", description = "用户交互载体")
@Data
public class User {
    @Schema(name = "用户id", type = "string")
    private String id;
    @Schema(name = "用户名", type = "string")
    private String name;
    @Schema(name = "密码", type = "string")
    private String password;
}
 

3.2 Controller 上

@RestController
@RequestMapping("/user")
@Tag(name = "用户管理", description = "用户数据增删改查")
public class UserController {
 
    @Autowired
    private UserService userService;
 
    @GetMapping("/{id}")
    @Operation(
            summary = "根据ID,查询用户",
            parameters = {
                    @Parameter(name = "id", required = true, in = ParameterIn.PATH)
            },
            responses = {
                    @ApiResponse(responseCode = "200",description = "成功",content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))),
                    @ApiResponse(responseCode = "400", description = "错误", content = @Content(mediaType = "application/json"))
            }
    )
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
}

3.3 分页场景

	@Operation(description = "searches inventory", operationId = "searchInventory", summary = "By passing in the appropriate options, you can search for available inventory in the system ", tags = {
			"developers", }, 
			parameters = {
			    @Parameter(description = "pass an optional search string for looking up inventory", name = "searchString") 
			}
    )
	
	@ApiResponses(value = {
	     @ApiResponse(responseCode = "200", description = "search results matching criteria"),
		 @ApiResponse(responseCode = "400", description = "bad input parameter") 
	})
	
	@GetMapping(value = "/inventory", produces = { "application/json" })
	ResponseEntity<List<InventoryItem>> searchInventory(
			@Valid @RequestParam(value = "searchString", required = false) String searchString,
			// 目标页数必须不是负数
			@Min(0) @Parameter(description = "number of records to skip for pagination") @Valid @RequestParam(value = "skip", required = true) Integer skip,
			// 返回的结果数不能大于50条记录
			@Min(0) @Max(50) @Parameter(description = "maximum number of records to return") @Valid @RequestParam(value = "limit", required = true) Integer limit);

你可能感兴趣的:(springcloud,SpringDoc)