在 Spring Boot 项目中，Swagger（主流分为 Swagger 2/Springfox 和 OpenAPI 3/SpringDoc）是接口文档生成的核心框架，而Knife4j是基于 Swagger 的增强版（完全兼容 Swagger 注解，同时新增少量专属增强注解）。以下是完整的注解分类及详解，包含 Swagger 2、OpenAPI 3（Swagger 3）、Knife4j 增强注解，附使用场景和示例。
一、核心说明
| 框架/版本 | 依赖核心 | 注解归属包 | 备注 |
|---|
| Swagger 2（Springfox） | springfox-swagger2 | io.swagger.annotations | 老版本主流，Spring Boot 2.6+ 需适配 |
| OpenAPI 3（Swagger 3） | springdoc-openapi | io.swagger.v3.oas.annotations | 新版本标准，兼容 Spring Boot 3.x |
| Knife4j | 基于 Swagger 增强 | 兼容上述所有 +com.github.xiaoymin | 美化UI、新增分组/权限等注解 |
二、Swagger 2（Springfox）核心注解（最常用）
1. 全局/配置类注解
| 注解 | 作用 | 使用位置 |
|---|
@EnableSwagger2 | 启用 Swagger 2 功能 | SpringBoot 配置类上 |
@EnableSwagger2WebMvc | 非 WebFlux 场景启用 Swagger 2（适配 Spring MVC） | 配置类上 |
2. 接口类注解
| 注解 | 作用 | 示例 |
|---|
@Api | 标记 Controller 类，描述接口分组信息 | @Api(tags = "用户管理接口", description = "用户CRUD操作") |
@ApiIgnore | 忽略当前类/方法/参数，不生成到接口文档中 | @ApiIgnore @RestController（忽略整个Controller） |
3. 接口方法注解
| 注解 | 作用 | 示例 |
|---|
@ApiOperation | 描述接口方法的功能、备注、响应等 | @ApiOperation(value = "根据ID查询用户", notes = "仅返回已激活用户", httpMethod = "GET") |
@ApiImplicitParams | 批量描述接口参数（配合@ApiImplicitParam使用） | 见下方参数示例 |
@ApiImplicitParam | 描述单个请求参数（路径、查询、请求头、表单等） | 见下方参数示例 |
@ApiResponses | 批量描述接口响应状态码（配合@ApiResponse使用） | 见下方响应示例 |
@ApiResponse | 描述单个响应状态码、信息、返回模型 | 见下方响应示例 |
4. 参数/请求体注解
| 注解 | 作用 | 示例 |
|---|
@ApiImplicitParam | 单个参数描述（非实体参数） | @ApiImplicitParams({@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long", paramType = "path"), @ApiImplicitParam(name = "token", value = "请求令牌", required = true, dataType = "String", paramType = "header")}) |
@ApiParam | 描述方法参数（直接加在参数前，替代@ApiImplicitParam） | public User getUser(@ApiParam(value = "用户ID", required = true) @PathVariable Long userId) |
@RequestBody | 标记请求体参数（非Swagger注解，但配合使用） | public Result save(@ApiParam(value = "用户信息", required = true) @RequestBody User user) |
5. 实体/字段注解
| 注解 | 作用 | 示例 |
|---|
@ApiModel | 描述实体类（请求体/响应体模型） | @ApiModel(value = "UserDTO", description = "用户请求参数模型") |
@ApiModelProperty | 描述实体字段的含义、是否必填、示例值、隐藏等 | @ApiModelProperty(value = "用户名", required = true, example = "zhangsan", hidden = false) private String username; |
Swagger 2 完整示例
// 配置类@Configuration@EnableSwagger2publicclassSwagger2Config{@BeanpublicDocketcreateRestApi(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(newApiInfoBuilder().title("SpringBoot Swagger2 接口文档").description("用户管理模块接口").version("1.0").build()).select().apis(RequestHandlerSelectors.basePackage("com.example.controller"))// 扫描包.paths(PathSelectors.any()).build();}}// Controller@RestController@RequestMapping("/user")@Api(tags="用户管理接口",description="用户CRUD操作")publicclassUserController{@GetMapping("/{userId}")@ApiOperation(value="根据ID查询用户",notes="仅返回已激活的用户信息")@ApiImplicitParams({@ApiImplicitParam(name="userId",value="用户ID",required=true,dataType="Long",paramType="path"),@ApiImplicitParam(name="token",value="请求令牌",required=true,dataType="String",paramType="header")})@ApiResponses({@ApiResponse(code=200,message="查询成功",response=UserDTO.class),@ApiResponse(code=404,message="用户不存在"),@ApiResponse(code=500,message="服务器内部错误")})publicResult<UserDTO>getUser(@PathVariableLonguserId,@RequestHeaderStringtoken){// 业务逻辑returnResult.success(newUserDTO());}@PostMapping("/save")@ApiOperation(value="新增用户",notes="用户名不能为空，密码长度≥6")publicResult<Void>save(@ApiParam(value="用户信息",required=true)@RequestBodyUserDTOuserDTO){// 业务逻辑returnResult.success();}}// 实体类@ApiModel(value="UserDTO",description="用户新增请求参数")publicclassUserDTO{@ApiModelProperty(value="用户名",required=true,example="zhangsan",hidden=false)privateStringusername;@ApiModelProperty(value="密码",required=true,example="123456",hidden=true)// 隐藏密码privateStringpassword;@ApiModelProperty(value="年龄",required=false,example="20")privateIntegerage;// getter/setter}
三、OpenAPI 3（Swagger 3/SpringDoc）核心注解（新版本推荐）
OpenAPI 3 是 Swagger 的标准化版本（OAS 3.0），注解包为io.swagger.v3.oas.annotations，完全替代 Swagger 2，适配 Spring Boot 3.x，Knife4j 也完全兼容。
注解映射（对比 Swagger 2）
| Swagger 2 注解 | OpenAPI 3 注解 | 作用一致？ | 补充说明 |
|---|
@Api | @Tag | 是 | @Tag(name = "用户接口", description = "...") |
@ApiOperation | @Operation | 是 | @Operation(summary = "查询用户", description = "...") |
@ApiImplicitParam | @Parameter | 是 | 加在参数前或@Parameters中 |
@ApiImplicitParams | @Parameters | 是 | 批量包裹@Parameter |
@ApiResponse | @ApiResponse | 是 | 包路径不同，参数兼容 |
@ApiResponses | @ApiResponses | 是 | 同上 |
@ApiModel | @Schema | 是 | 加在实体类上，替代@ApiModel |
@ApiModelProperty | @Schema | 是 | 加在字段上，替代@ApiModelProperty |
@ApiParam | @Parameter | 是 | 加在参数前 |
@ApiIgnore | @Hidden | 是 | 忽略类/方法/参数 |
OpenAPI 3 核心注解详解
| 注解 | 作用 | 使用位置 | 示例 |
|---|
@OpenAPIDefinition | 全局配置（替代 Swagger 2 的ApiInfo） | 配置类/启动类 | @OpenAPIDefinition(info = @Info(title = "OpenAPI 3 文档", version = "1.0", description = "...")) |
@Tag | 标记 Controller 类（替代@Api） | Controller 类上 | @Tag(name = "用户管理", description = "用户CRUD") |
@Operation | 描述方法（替代@ApiOperation） | 接口方法上 | @Operation(summary = "查询用户", description = "根据ID查用户", tags = {"用户管理"}) |
@Parameter | 描述单个参数（替代@ApiImplicitParam/@ApiParam） | 方法参数前/@Parameters | @Parameter(name = "userId", description = "用户ID", required = true, in = ParameterIn.PATH) |
@Parameters | 批量描述参数（替代@ApiImplicitParams） | 方法上 | @Parameters({@Parameter(...), @Parameter(...)}) |
@Schema | 描述实体类/字段（替代@ApiModel/@ApiModelProperty） | 实体类/字段上 | 类：@Schema(name = "UserDTO", description = "用户参数")；字段：@Schema(description = "用户名", required = true, example = "zhangsan") |
@ApiResponse | 描述响应（包路径：io.swagger.v3.oas.annotations.responses） | 方法上/@ApiResponses | @ApiResponse(responseCode = "200", description = "成功", content = @Content(schema = @Schema(implementation = UserDTO.class))) |
@Hidden | 忽略元素（替代@ApiIgnore） | 类/方法/参数/字段 | @Hidden @GetMapping("/test") |
OpenAPI 3 完整示例
// 配置类（Spring Boot 3.x）@ConfigurationpublicclassOpenApi3Config{@BeanpublicOpenAPIcustomOpenAPI(){returnnewOpenAPI().info(newInfo().title("SpringBoot OpenAPI 3 接口文档").version("1.0").description("基于Knife4j增强的OpenAPI 3文档")).components(newComponents()// 全局请求头（如token）.addParameters("token",newParameter().name("token").description("请求令牌").required(true).in(ParameterIn.HEADER.toString()).schema(newSchema().type("string"))));}}// Controller@RestController@RequestMapping("/user")@Tag(name="用户管理接口",description="OpenAPI 3 示例接口")publicclassUserController{@GetMapping("/{userId}")@Operation(summary="根据ID查询用户",description="仅返回已激活用户，需携带token请求头")@Parameters({@Parameter(name="userId",description="用户ID",required=true,in=ParameterIn.PATH),@Parameter(name="token",description="请求令牌",required=true,in=ParameterIn.HEADER)})@ApiResponses({@ApiResponse(responseCode="200",description="查询成功",content=@Content(schema=@Schema(implementation=UserDTO.class))),@ApiResponse(responseCode="404",description="用户不存在"),@ApiResponse(responseCode="500",description="服务器错误")})publicResult<UserDTO>getUser(@PathVariableLonguserId,@RequestHeaderStringtoken){returnResult.success(newUserDTO());}@PostMapping("/save")@Operation(summary="新增用户",description="用户名必填，密码≥6位")@ApiResponse(responseCode="200",description="新增成功")publicResult<Void>save(@Parameter(description="用户信息",required=true)@RequestBodyUserDTOuserDTO){returnResult.success();}}// 实体类@Schema(name="UserDTO",description="用户新增请求参数模型")publicclassUserDTO{@Schema(description="用户名",required=true,example="zhangsan")privateStringusername;@Schema(description="密码",required=true,example="123456",hidden=true)privateStringpassword;@Schema(description="年龄",required=false,example="20")privateIntegerage;// getter/setter}
四、Knife4j 专属增强注解
Knife4j 基于 Swagger/SpringDoc 扩展，除了兼容所有原生注解，还新增了分组、权限、文档导出等增强注解，核心如下：
| 注解 | 作用 | 使用位置 | 示例 |
|---|
@EnableKnife4j | 启用 Knife4j 增强功能（替代@EnableSwagger2，兼容 OpenAPI 3） | 配置类上 | @Configuration @EnableKnife4j public class Knife4jConfig {...} |
@ApiOperationSupport | Knife4j 增强的方法注解（排序、忽略参数、多语言等） | 接口方法上 | @ApiOperationSupport(order = 1, ignoreParameters = "password") |
@DynamicParameter | 动态参数注解（适配Map类型参数） | 方法/参数上 | @DynamicParameters(name = "params", properties = {@DynamicParameter(name = "key", value = "值", example = "test")}) |
@ApiSort | 接口分组排序（替代@ApiOperationSupport的 order） | Controller 类上 | @ApiSort(1) @Tag(name = "用户接口") |
Knife4j 增强示例（基于 OpenAPI 3）
@Configuration@EnableOpenApi// OpenAPI 3 启用@EnableKnife4j// 启用Knife4j增强publicclassKnife4jConfig{@BeanpublicOpenAPIcustomOpenAPI(){returnnewOpenAPI().info(newInfo().title("Knife4j 增强文档").version("1.0"));}}@RestController@RequestMapping("/user")@Tag(name="用户管理接口")@ApiSort(1)// 分组排序（1优先显示）publicclassUserController{@PostMapping("/save")@Operation(summary="新增用户")@ApiOperationSupport(order=1,// 方法排序ignoreParameters="password"// 忽略密码参数显示)publicResult<Void>save(@RequestBodyUserDTOuserDTO){returnResult.success();}// 动态参数（Map入参）@PostMapping("/dynamic")@Operation(summary="动态参数示例")@DynamicParameters(name="DynamicParam",properties={@DynamicParameter(name="name",value="名称",example="测试"),@DynamicParameter(name="value",value="值",example="123")})publicResult<Void>dynamic(@RequestBodyMap<String,Object>params){returnResult.success();}}
五、关键注意事项
- 版本兼容：
- Spring Boot 2.x 可混用 Swagger 2（springfox）或 OpenAPI 3（springdoc）；
- Spring Boot 3.x 仅支持 OpenAPI 3（springdoc），Knife4j 4.x 适配 Spring Boot 3.x。
- 敏感信息隐藏：
- 密码、令牌等字段用
@Schema(hidden = true)（OpenAPI 3）或@ApiModelProperty(hidden = true)（Swagger 2）隐藏。
- Knife4j 访问地址：
- Swagger 2 + Knife4j：
http://localhost:8080/doc.html（核心，替代原生swagger-ui.html）； - OpenAPI 3 + Knife4j：同上，原生地址
http://localhost:8080/swagger-ui/index.html。
- 生产环境关闭：
@Profile({"dev","test"})// 仅开发/测试环境启用@Configuration@EnableKnife4jpublicclassKnife4jConfig{...}
六、核心依赖（Maven）
1. Swagger 2 + Knife4j（Spring Boot 2.x）
<!-- Swagger 2 核心 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!-- Knife4j 增强 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version></dependency>
2. OpenAPI 3 + Knife4j（Spring Boot 3.x）
<!-- SpringDoc OpenAPI 3 核心 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.2.0</version></dependency><!-- Knife4j 增强 OpenAPI 3 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency>
以上注解覆盖了接口文档生成的所有核心场景（分组、参数、响应、实体、动态参数、权限隐藏等），Knife4j 完全兼容 Swagger 原生注解，优先推荐使用 OpenAPI 3（Swagger 3）+ Knife4j 的组合，适配最新 Spring Boot 版本。
