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

多个参数统一包裹（不常用，一般直接每个参数加 @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 生成）