OpenAPI 3.0（Swagger3/Knife4j）完整简洁注解清单

适配Spring Boot3.x + Knife4j v4.x，替代Swagger2旧注解 ，所有注解均来自io.swagger.v3.oas.annotations及子包，按类/方法/参数/请求体/响应/通用分类，核心属性+用途极简说明，可直接复制使用。

一、类级别（Controller上）

注解	核心用途	核心属性
`@Tag`	描述控制器模块信息（替代Swagger2`@Api`）	`name`(必填)：模块名；`description`：功能说明；`order`：排序（数字越小越靠前）

示例：

java 复制代码

@Tag(name = "用户管理", description = "用户增删改查接口", order = 1)
@RestController
public class UserController {}

二、方法级别（Controller方法上）

注解	核心用途	核心属性
`@Operation`	描述单个接口功能（替代Swagger2`@ApiOperation`）	`summary`(必填)：接口简短名称；`description`：详细说明；`hidden`：是否隐藏（true/false）
`@Hidden`	单独隐藏接口（语义更清晰，替代`@Operation(hidden=true)`）	无属性

示例：

java 复制代码

@Operation(summary = "根据ID查用户", description = "查询用户详情及关联角色")
@GetMapping("/{id}")
public Result<UserVO> getById() {}

@Hidden
@GetMapping("/test")
public Result<String> test() {}

三、简单参数注解（方法参数上：路径/请求参数/请求头）

注解	核心用途	核心属性
`@Parameter`	描述单个简单参数（替代Swagger2`@ApiParam`），适配`@PathVariable`/`@RequestParam`/`@RequestHeader`	`name`：参数名；`description`：说明；`required`：是否必填；`example`：示例值；`hidden`：是否隐藏

示例：

java 复制代码

@GetMapping("/list")
public Result<List<UserVO>> list(
    @Parameter(name = "pageNum", description = "页码", required = true, example = "1") @RequestParam Integer pageNum,
    @Parameter(name = "token", description = "请求令牌") @RequestHeader String token
) {}

四、复杂参数/请求体注解（方法参数上）

注解	核心用途	适用场景
`@RequestBody`	描述JSON请求体，说明请求体含义	POST/PUT请求的JSON入参（如DTO对象）
`@ParameterObject`	自动解析封装对象的所有字段为接口参数	多参数封装为DTO/VO（如分页查询、高级查询），替代多个`@RequestParam`

示例：

java 复制代码

// 单个JSON请求体
@PostMapping("/add")
public Result<Boolean> add(
    @RequestBody(description = "新增用户参数，用户名/密码为必填") UserAddDTO dto
) {}

// 封装参数对象
@GetMapping("/page")
public Result<Page<UserVO>> page(
    @ParameterObject(description = "用户分页查询参数") UserQueryDTO queryDTO
) {}

五、响应结果注解（方法/类上）

注解	核心用途	核心属性
`@ApiResponse`	描述单个响应状态码及含义	`responseCode`：状态码（如200/400）；`description`：说明；`content`：响应体类型
`@ApiResponses`	组合多个`@ApiResponse`，描述多状态码响应	仅`value`：数组，包含多个`@ApiResponse`

示例：

java 复制代码

@Operation(summary = "删除用户")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "删除成功"),
    @ApiResponse(responseCode = "400", description = "参数错误，用户ID不能为空"),
    @ApiResponse(responseCode = "404", description = "用户不存在")
})
@DeleteMapping("/{id}")
public Result<Boolean> delete(@PathVariable Long id) {}

六、模型/实体注解（DTO/VO/实体类上/字段上）

用于描述接口入参/出参的实体对象，文档中自动渲染字段说明，替代Swagger2@ApiModel/@ApiModelProperty。

|------|----------|----------|

| @Schema | 字段上 | 描述字段含义、约束、示例 | description：字段说明；required：是否必填；example：示例值；hidden：是否隐藏；allowableValues：可选值（如{"0","1"}） |

示例：

java 复制代码

@Data
@Schema(title = "新增用户DTO", description = "新增用户的请求参数模型")
public class UserAddDTO {
    @Schema(description = "用户名", required = true, example = "zhangsan")
    private String username;
    
    @Schema(description = "密码", required = true, example = "123456")
    private String password;
    
    @Schema(description = "用户状态", example = "1", allowableValues = {"0","1"}, notes = "0-禁用 1-启用")
    private Integer status;
    
    @Schema(hidden = true)
    private String createTime;
}

七、通用配置注解（主启动类/配置类上）

注解	核心用途	适用场景
`@OpenAPIDefinition`	全局配置OpenAPI文档信息	主启动类上，配置文档标题、版本、描述、联系人等（替代配置类中手动构建OpenAPI对象）
`@Info`	配合`@OpenAPIDefinition`使用，描述文档核心信息	作为`@OpenAPIDefinition`的`info`属性
`@Contact`	配合`@Info`使用，配置文档联系人信息	作为`@Info`的`contact`属性

示例：

java 复制代码

@SpringBootApplication
@OpenAPIDefinition(
    info = @Info(
        title = "IAM微服务API文档",
        version = "1.0.0",
        description = "用户/角色/权限管理接口文档",
        contact = @Contact(name = "Dragon Wu", email = "dragon.wu@xloda.com")
    )
)
public class IamServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(IamServiceApplication.class, args);
    }
}

八、核心备注

包路径 ：所有注解均在io.swagger.v3.oas.annotations下，子注解（如@Tag/@Schema）在对应子包（tags/schema），IDE可自动导入；
兼容Knife4j ：无需额外配置，注解会自动渲染到Knife4j的/doc.html文档页面；
替代关系 ：完全替代Swagger2的springfox-swagger2注解，无需混合使用，避免依赖冲突；
极简原则 ：非必填属性可省略，核心属性（name/summary/required）按需填写，保证文档简洁可用。