SpringDoc注解解析

一、什么是SpringDoc

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

二、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 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 = "用户实体类")@Datapublic 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 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 = "用户交互载体")@Datapublic 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 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);