须要把稳的是 springdoc-openapi 支持多个 SpringBoot 版本，不同的 SpringBoot 须要选择对应的 springdoc-openapi 版本。
springdoc-openapi v1 支持 SpringBoot v1/v2springdoc-openapi v2 支持 SpringBoot v3本文先容 SpringDoc OpenAPI 3，“俗称 Swagger 3” 常见的表明。
SpringDoc 官网地址：https://springdoc.org/
1. OpenApi 3 的紧张表明
下表对照 Swagger2 的表明，列出了 OpenAPI 3 的紧张表明。
Swagger2
Swagger3 (OpenApi)
@Api
@Tag
@ApiIgnore
@Operation(hidden=true), @Parameter(hidden=true), @Hidden
@ApiModel
@Schema
@ApiModelProperty
@Schema
@ApiOperation(value="简述", notes="详述")
@Operation(summary="简述", description="详述")
@ApiParam
@Parameter
@ApiImplicitParam
@Parameter
@ApiImplicitParams
@Parameters
@ApiResponse(code=404, message="")
@ApiResponse(responseCode="404", description="")
2. @Tag 表明
@Tag 常日用在 Controller 类上，用于解释类浸染，也可以浸染于方法上。
紧张参数：
name：Tag名称，常日用于 API 分组description：该分组的描述@Tag
@Tag(name = "用户管理接口", description = "定义了与用户干系的接口")@RestController@RequestMapping("usr")public class UserController {}
@Parameter 用于描述 API 的参数，@Parameters 将多个 @Parameter 封装到一起。
紧张参数：
name：参数名称in：参数来源，默认为空ParameterIn.QUERY 查询参数ParameterIn.PATH 路径参数ParameterIn.HEADER header参数ParameterIn.COOKIE cookie 参数description：参数描述required：是否必填，默认为 falseschema ：描述参数的数据类型，取值范围等，如 schema = @Schema(type = “string”)hidden：是否隐蔽，默认为 false@Parameter
@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)，但界面上还是显示必填项的缘故原由。
required=false无效
ParameterIn.QUERY 类型的参数，如果指定了 defaultValue，也会被标记为 required。路径变量 @PathVariable，是必填的，设置了 @Parameter(required=false) 也不会起浸染：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;}
allowableValues
5. @Operation 表明常日用在 Controller 的接口方法上，用于描述接口的名称、要求方法、参数列表，相应代码等。
紧张参数：
summary：简短描述description ：详细描述hidden：是否隐蔽tags：用于分组 API，默认与接口所在类上的 @Tag 表明的值相同parameters：指定干系的要求参数，利用 @Parameter 来定义各参数的详细属性。requestBody：指定要求的内容，利用 @RequestBody 來指定要求的类型。responses：指定操作的返回内容，利用 @ApiResponse 表明定义返回值的详细属性。@Operation
@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";}
一样平常用于接口上，解释接口的相应信息，不常利用。
紧张参数：
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");}
用于描述实体类及其属性，包括示例、验证规则等。
紧张参数：
name：名称title：标题description：描述defaultValue：默认值example：示例值type： 数据类型 integer，long，float，double，string，byte，binary，boolean，date、datetime，password@Schema(title = "User", description = "用户工具")@Datapublic 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;}
@Schema
8. @Hidden 表明@Hidden 用于掌握某个元素（API、实体类属性等）在 API 文档中是否要隐蔽。与 @Parameter(hidden = false)、@Operation(hidden = false) 浸染类似。
@Hidden
