SpringDoc OpenAPI 3 常用注解使用方法
作者：伯恩bourne
本文介绍了SpringDoc/OpenAPI3在SpringBoot4+项目中的常用注解,包括@Tag、@Operation、@Parameter、@ApiResponse等核心注解,以及@Schema、@Hidden、@Parameters等实用注解的使用方法,并提供了一个完整示例,感兴趣的朋友跟随小编一起看看吧
SpringDoc / OpenAPI 3 最常用注解，适配 Spring Boot 4 + springdoc-openapi 3.x，直接复制就能用。
一、核心常用注解（必掌握）
1.@Tag
作用：给 Controller / 接口模块 打标签，用于分组显示。
@RestController
@RequestMapping("/user")
@Tag(name = "用户管理模块", description = "用户的增删改查接口")
public class UserController {
}
效果：Swagger UI 左侧会显示一个分组：用户管理模块
2.@Operation
作用：描述单个接口方法，相当于接口说明。
@Operation(
summary = "根据ID查询用户",
description = "传入用户ID，返回用户详细信息",
tags = {"用户管理模块"}
)
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
}
常用属性：
summary：接口简短说明description：详细描述tags：归属分组method：请求方法（一般不用写，自动识别）hidden：是否隐藏接口
3.@Parameter
作用：描述路径参数 / 查询参数。
@GetMapping("/{id}")
public User getUser(
@Parameter(description = "用户ID", required = true, example = "1001")
@PathVariable Long id
) {
}
常用属性：
description：参数说明required：是否必填example：示例值hidden：隐藏参数
4.@ApiResponse/@ApiResponses
作用：定义接口响应状态码与说明。
@Operation(...)
@ApiResponses({
@ApiResponse(responseCode = "200", description = "查询成功"),
@ApiResponse(responseCode = "404", description = "用户不存在"),
@ApiResponse(responseCode = "500", description = "服务器异常")
})
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
}
二、实体类常用注解
5.@Schema
作用：描述DTO、实体类、字段的含义、示例、约束。
用在类上
@Schema(description = "用户信息实体")
public class User {
}
用在字段上
@Schema(description = "用户ID", example = "1001") private Long id; @Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED) private String username;
常用属性：
description：字段说明example：示例requiredMode：是否必填hidden：隐藏字段minLength / maxLength：长度限制format：格式（password、email 等）
三、实用增强注解
6.@Hidden
作用：隐藏某个接口、类、字段，不在 Swagger 显示。
@Hidden
@GetMapping("/internal")
public void internalApi() {
}
7.@Parameters
多个参数统一包裹（不常用，一般直接每个参数加 @Parameter）
8.@RequestBody搭配 OpenAPI
SpringDoc 会自动识别 @RequestBody，你只需要给 DTO 加 @Schema 即可。
四、完整示例（可直接复制）
@RestController
@RequestMapping("/user")
@Tag(name = "用户管理模块", description = "用户相关接口")
public class UserController {
@Operation(
summary = "根据ID查询用户",
description = "根据用户唯一ID查询用户详情"
)
@ApiResponses({
@ApiResponse(responseCode = "200", description = "成功"),
@ApiResponse(responseCode = "404", description = "用户不存在")
})
@GetMapping("/{id}")
public User getUser(
@Parameter(description = "用户ID", required = true, example = "1001")
@PathVariable Long id
) {
return new User();
}
}@Schema(description = "用户信息")
public class User {
@Schema(description = "用户ID", example = "1001")
private Long id;
@Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED)
private String username;
}五、访问地址
启动后访问：
http://localhost:端口/swagger-ui.html
（注：文档部分内容由 AI 生成）
到此这篇关于SpringDoc OpenAPI 3 常用注解使用方法的文章就介绍到这了,更多相关SpringDoc OpenAPI 3 注解内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！