springdoc-openapi-ui有哪些注解
时间: 2025-05-29 19:17:18 浏览: 39
<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]
---
阅读全文
相关推荐


















