OpenAPI3常用注解

OpenAPI 规范 (中文版) (apifox.cn)

目录

1.@Operation

2.@Parameter

3.@Parameters

4.@Schema

5.@ApiResponse

6.@Tag

1.@Operation

用于描述一个 API 操作，通常应用于控制器方法上。

参数：

• summary：接口的简要描述。
• description：接口的详细描述。
• tags：接口所属的标签组。
• responses：定义可能的响应结果及其状态码。

示例：

@Operation(summary = "获取用户信息", description = "根据用户ID获取用户详细信息")
@GetMapping("/user/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // 方法体
}

2.@Parameter

用于描述请求中的单个参数，可以应用于方法参数上。

参数：

• name：参数名称。
• description：参数描述。
• required：是否为必填项。
• in：参数的位置（如 PATH、QUERY、HEADER 等）。

示例：

@Operation(summary = "获取用户信息")
@GetMapping("/user/{id}")
public ResponseEntity<User> getUserById(
    @Parameter(name = "id", description = "用户ID", required = true, in = ParameterIn.PATH) @PathVariable Long id) {
    // 方法体
}

3. @Parameters

用于定义多个参数的注解容器。@Parameters包含多个@Parameter注解。

@Operation(summary = "更新用户信息")
@PutMapping("/user/{id}")
@Parameters({
    @Parameter(name = "id", description = "用户ID", required = true, in = ParameterIn.PATH),
    @Parameter(name = "token", description = "用户认证Token", in = ParameterIn.HEADER)
})
public ResponseEntity<Void> updateUser(@PathVariable Long id, @RequestHeader String token, @RequestBody User user) {
    // 方法体
}

4.@Schema

用于描述对象模型和字段，通常用于实体类或 DTO 类上。

参数：

• description：字段描述。
• example：字段的示例值。
• required：字段是否为必填项。
• type：字段的数据类型。

public class User {
    @Schema(description = "用户ID", example = "123")
    private Long id;

    @Schema(description = "用户名", example = "john_doe")
    private String username;
}

5. @ApiResponse

用于描述单个 API 响应。通常和 @Operation 一起使用。

参数：

• responseCode：HTTP 状态码。
• description：响应描述。

示例：

@Operation(summary = "删除用户", description = "根据用户ID删除用户")
@ApiResponse(responseCode = "200", description = "成功删除用户")
@ApiResponse(responseCode = "404", description = "用户未找到")
@DeleteMapping("/user/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    // 方法体
}

6.@Tag

用于对接口进行分类，方便在文档中分组显示。

参数：

• name：标签名称。
• description：标签描述。

示例：

@Tag(name = "用户管理", description = "用户相关操作")
@RestController
@RequestMapping("/user")
public class UserController {
    // 控制器方法
}