SpringBoot 项目整合 SpringDoc OpenAPI 是非常简单的，基本上添加依赖后即可使用，可以参看这篇文章。

需要注意的是 springdoc-openapi 支持多个 SpringBoot 版本，不同的 SpringBoot 需要选择对应的 springdoc-openapi 版本。

• springdoc-openapi v1 支持 SpringBoot v1/v2
• springdoc-openapi v2 支持 SpringBoot v3

本文介绍 SpringDoc OpenAPI 3，“俗称 Swagger 3” 常见的注解。

SpringDoc 官网地址：https://springdoc.org/

1. OpenApi 3 的主要注解

下表对照 Swagger2 的注解，列出了 OpenAPI 3 的主要注解。

2. @Tag 注解

@Tag 通常用在 Controller 类上，用于说明类作用，也可以作用于方法上。

主要参数：

• name：Tag名称，通常用于 API 分组
• description：该分组的描述

@Tag(name = "用户管理接口", description = "定义了与用户相关的接口")
@RestController
@RequestMapping("usr")
public class UserController {}

3. @Parameter 和 @Parameters

@Parameter 用于描述 API 的参数，@Parameters 将多个 @Parameter 封装到一起。

主要参数：

• name：参数名称
• in：参数来源，默认为空
• ParameterIn.QUERY 查询参数
• ParameterIn.PATH 路径参数
• ParameterIn.HEADER header参数
• ParameterIn.COOKIE cookie 参数
• description：参数描述
• required：是否必填，默认为 false
• schema ：描述参数的数据类型，取值范围等，如 schema = @Schema(type = “string”)
• hidden：是否隐藏，默认为 false

@GetMapping("findPet")
public String findPet(@Parameter(name = "usrId", 
                          description = "用户ID", 
                          in = ParameterIn.QUERY, 
                          schema = @Schema(type = "integer"), 
                          required=true)
                      @RequestParam Long usrId,                       
                      @Parameter(name = "petId", 
                           description = "宠物ID", 
                           in = ParameterIn.QUERY)
                      @RequestParam(required = false) Long petId) {
    return "elephant";
}

关于“required 是否必填”的几点说明

• swagger-ui 界面上看到的 “是否为必填”，是由@Parameter(required=true or false) 和 @RequestParam(required=true or false) 共同作用的结果。这也就是有时明明设置了 @Parameter(required=false)，但界面上还是显示必填项的原因。

• ParameterIn.QUERY 类型的参数，如果指定了 defaultValue，也会被标记为 required。
• 路径变量 @PathVariable，是必填的，设置了 @Parameter(required=false) 也不会起作用：

4. 参数的枚举取值范围 allowableValues

可用通过 @Schema(allowableValues = {"cat", "dog"}) 来实现。

@GetMapping("getPetCount")
public Integer getPetCount(@Parameter(name="petType",
                          description="宠物类型",
                          schema=@Schema(type = "string",
                          allowableValues = {"cat", "dog"}))
                          String petType) {
    return 0;
}

5. @Operation 注解

通常用在 Controller 的接口方法上，用于描述接口的名称、请求方法、参数列表，响应代码等。

主要参数：

• summary：简短描述
• description ：详细描述
• hidden：是否隐藏
• tags：用于分组 API，默认与接口所在类上的 @Tag 注解的值相同
• parameters：指定相关的请求参数，使用 @Parameter 来定义各参数的详细属性。
• requestBody：指定请求的内容，使用 @RequestBody 來指定请求的类型。
• responses：指定操作的返回内容，使用 @ApiResponse 注解定义返回值的详细属性。

@Operation(
    summary = "获取指定用户的指定宠物信息",
    description = "根据 usrId 和 petId 获取宠物信息",
    parameters = {
        @Parameter(name = "usrId", description = "用户ID", in = ParameterIn.PATH, schema = @Schema(type = "integer")),
        @Parameter(name = "petId", description = "宠物ID", in = ParameterIn.PATH)},
    responses = {@ApiResponse(responseCode = "200", description = "成功")}
)
@GetMapping("{usrId}/pets/{petId}")
public String getPet(@PathVariable Long usrId, @PathVariable Long petId) {
    log.info("[getPet] {}, {}", usrId, petId);
    return "tiger";
}

6. @ApiResponse 注解

一般用于接口上，说明接口的响应信息，不常使用。

主要参数：

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

@ApiResponse(responseCode = "200", description = "成功")
public Integer listUsers() {
}

@Operation(summary = "Get thing", responses = {
      @ApiResponse(description = "Successful Operation", responseCode = "200", content = @Content(mediaType = "application/json", schema = @Schema(implementation = String.class))),
      @ApiResponse(responseCode = "404", description = "Not found", content = @Content),
      @ApiResponse(responseCode = "401", description = "Authentication Failure", content = @Content(schema = @Schema(hidden = true))) })
@RequestMapping(path = "/testme", method = RequestMethod.GET)
ResponseEntity<String> testme() {
   return ResponseEntity.ok("Hello");
}

7. @Schema 注解

用于描述实体类及其属性，包括示例、验证规则等。

主要参数：

• name：名称
• title：标题
• description：描述
• defaultValue：默认值
• example：示例值
• type： 数据类型 integer，long，float，double，string，byte，binary，boolean，date、datetime，password

@Schema(title = "User", description = "用户对象")
@Data
public class UserEntity {
    @Schema(description = "序号", example = "1", type = "long")
    private Long seq;
    @Schema(description = "姓名", example = "张三", type = "string")
    private String name;
    @Schema(description = "性别", example = "男", type = "string")
    private String gender;
    @Schema(description = "生日", example = "2000-01-01", type = "string", format = "date")
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    private Date birthday;
}

8. @Hidden 注解

@Hidden 用于控制某个元素（API、实体类属性等）在 API 文档中是否要隐藏。与 @Parameter(hidden = false)、@Operation(hidden = false) 作用类似。