springdoc-openapi-ui有哪些注解

<think>好的，我需要回答用户关于springdoc-openapi-ui支持的注解及其用法的问题。首先，我得回忆一下用户提供的引用内容。引用[1]提到了引入依赖的方法，引用[2]和[3]则涉及了Swagger、OpenAPI以及迁移到springdoc-openapi的信息。根据这些资料，我应该整理出相关的注解。 首先，用户想知道支持的注解列表及作用。我记得springdoc-openapi主要支持OpenAPI 3的注解，可能包括@Tag、@Operation、@Parameter、@ApiResponse等。需要逐个列举每个注解的用途，并给出代码示例。 比如，@Tag用于分类API，@Operation描述单个操作，@Parameter定义参数细节，@ApiResponse说明响应状态。这些注解在Spring Boot的控制器类和方法上使用，帮助生成API文档。同时，可能还有@Schema用于模型定义，@RequestBody描述请求体，@SecurityRequirement设置安全需求。 需要确保每个注解都有对应的中文解释和示例代码，符合用户要求的中文回答。另外，根据系统指令，数学公式要用$...$，但这里可能不需要。代码块需要用正确的语法，比如Java的代码示例。 还要注意引用来源，用户提供的三个引用中，引用[3]提到了迁移和注解替换，可能涉及从Springfox到springdoc的注解变化，比如@Api变成@Tag。需要指出这些变化，帮助用户正确迁移。 最后，生成相关问题，可能涉及如何配置、与旧版区别、安全配置等。检查是否有遗漏的注解，确保覆盖主要常用的注解，并准确对应到springdoc-openapi-ui的文档支持。</think>关于springdoc-openapi-ui支持的注解及作用，以下是主要注解列表及使用示例： --- ### 1. **核心注解** #### @Tag - **作用**：定义API分组或模块分类 - **示例**： ```java @Tag(name = "用户管理", description = "用户注册、登录、信息维护") @RestController public class UserController {} ``` #### @Operation - **作用**：描述单个接口操作 - **示例**： ```java @Operation( summary = "创建用户", description = "通过手机号注册新用户", tags = {"用户管理"} ) @PostMapping("/users") public User createUser(@RequestBody User user) {} ``` --- ### 2. **参数相关** #### @Parameter - **作用**：定义接口参数细节 - **示例**： ```java @GetMapping("/users") public List<User> getUsers( @Parameter( name = "status", description = "用户状态过滤", example = "ACTIVE", required = true, schema = @Schema(allowableValues = {"ACTIVE", "INACTIVE"}) ) @RequestParam String status) {} ``` #### @RequestBody - **作用**：描述请求体结构 - **示例**： ```java @PostMapping("/login") public ResponseEntity login( @io.swagger.v3.oas.annotations.parameters.RequestBody( description = "登录凭证", required = true, content = @Content(schema = @Schema(implementation = LoginDTO.class)) ) @RequestBody LoginDTO dto) {} ``` --- ### 3. **响应相关** #### @ApiResponse - **作用**：定义接口响应状态码和说明 - **示例**： ```java @ApiResponse( responseCode = "201", description = "资源创建成功", content = @Content(schema = @Schema(implementation = User.class)) ) @ApiResponse( responseCode = "400", description = "无效的请求参数" ) ``` --- ### 4. **模型定义** #### @Schema - **作用**：定义数据模型属性 - **示例**： ```java public class User { @Schema(description = "用户ID", example = "10001", accessMode = READ_ONLY) private Long id; @Schema(description = "用户名", example = "张三", minLength = 2, maxLength = 20) private String name; } ``` --- ### 5. **安全相关** #### @SecurityRequirement - **作用**：声明接口的安全需求 - **示例**： ```java @SecurityRequirement(name = "JWT") @GetMapping("/profile") public User getProfile() {} ``` --- ### 迁移注意 从Springfox迁移时需注意注解替换： - `@Api` → `@Tag` - `@ApiOperation` → `@Operation` - `@ApiParam` → `@Parameter` - `@ApiModel` → `@Schema` - `@ApiResponse` 保持同名但包路径变化[^3] ---