SpringDoc OpenAPI 3 常用注解详解

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多个参数统一包裹不常用一般直接每个参数加Parameter8.RequestBody搭配 OpenAPISpringDoc 会自动识别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 生成