swagger全部注解，附swagger2和swagger3的注解区别

系列文章：
springboot-swagger详解
springboot-优美的Knife4j文档-Swagger进化
Spring Cloud Gateway 网关整合 Knife4j
SpringBoot之如何集成SpringDoc最详细文档

1. 核心注解

@Api

• 作用：用于标记一个类是 API 的入口点。
• 常用属性：
  • tags：为 API 分组。
  • description：API 的描述信息。
• 示例：

  @Api(tags = "用户管理", description = "用户相关的操作")
  @RestController
  @RequestMapping("/users")
  public class UserController {
      // ...
  }
  

---

2. 方法级别注解

@ApiOperation

• 作用：描述一个 API 方法的功能。
• 常用属性：
  • value：方法的简短描述。
  • notes：方法的详细描述。
  • response：指定返回值类型。
  • httpMethod：指定 HTTP 方法（如 GET、POST 等）。
• 示例：

  @ApiOperation(value = "获取用户列表", notes = "返回所有用户的详细信息")
  @GetMapping
  public List<User> getUsers() {
      // ...
  }
  

@ApiResponses 和 @ApiResponse

• 作用：描述一个 API 方法可能的响应结果。
• 常用属性：
  • code：HTTP 状态码。
  • message：响应的描述信息。
  • response：响应的数据类型。
• 示例：

  @ApiOperation(value = "创建用户", notes = "根据用户信息创建新用户")
  @ApiResponses({
      @ApiResponse(code = 200, message = "成功创建用户"),
      @ApiResponse(code = 400, message = "请求参数错误"),
      @ApiResponse(code = 500, message = "服务器内部错误")
  })
  @PostMapping
  public ResponseEntity<User> createUser(@RequestBody User user) {
      // ...
  }
  

---

3. 参数相关注解

@ApiParam

• 作用：描述方法参数的含义。
• 常用属性：
  • name：参数名称。
  • value：参数的描述信息。
  • required：是否必填。
  • example：参数的示例值。
• 示例：

  @ApiOperation(value = "根据 ID 获取用户")
  @GetMapping("/{id}")
  public User getUserById(
      @ApiParam(name = "id", value = "用户 ID", required = true, example = "1") 
      @PathVariable Long id) {
      // ...
  }
  

@ApiImplicitParams 和 @ApiImplicitParam

• 作用：描述非显式声明的参数（如查询参数、表单参数等）。
• 常用属性：
  • name：参数名称。
  • value：参数的描述信息。
  • paramType：参数类型（如 path、query、header 等）。
  • dataType：参数的数据类型。
• 示例：

  @ApiOperation(value = "搜索用户")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "name", value = "用户名", paramType = "query", dataType = "string"),
      @ApiImplicitParam(name = "age", value = "用户年龄", paramType = "query", dataType = "int")
  })
  @GetMapping("/search")
  public List<User> searchUsers(@RequestParam String name, @RequestParam Integer age) {
      // ...
  }
  

---

4. 模型相关注解

@ApiModel

• 作用：描述一个实体类的模型。
• 常用属性：
  • value：模型的名称。
  • description：模型的描述信息。
• 示例：

  @ApiModel(value = "用户模型", description = "用户的基本信息")
  public class User {
      private Long id;
      private String name;
      private Integer age;
      // getters and setters
  }
  

@ApiModelProperty

• 作用：描述实体类中字段的信息。
• 常用属性：
  • value：字段的描述信息。
  • example：字段的示例值。
  • required：是否必填。
  • hidden：是否隐藏该字段。
• 示例：

  @ApiModel(value = "用户模型", description = "用户的基本信息")
  public class User {
      @ApiModelProperty(value = "用户 ID", example = "1", required = true)
      private Long id;
  
      @ApiModelProperty(value = "用户名", example = "John Doe", required = true)
      private String name;
  
      @ApiModelProperty(value = "用户年龄", example = "25")
      private Integer age;
      // getters and setters
  }
  

---

5. 其他注解

@ApiIgnore

• 作用：忽略某个类、方法或参数，不将其包含在生成的文档中。
• 示例：

  @ApiIgnore
  @GetMapping("/internal")
  public String internalEndpoint() {
      return "This endpoint is ignored by Swagger.";
  }
  

@ApiModelProperty

• 作用：类似于 @ApiModelProperty，但更适用于复杂嵌套对象的字段描述。

---

6、swagger2.0注解总结

注解	作用	常用属性	示例代码
@Api	标记一个类是 API 的入口点，描述整个控制器的功能。	tags：API 分组 description：API 描述信息	java @Api(tags = "用户管理", description = "用户相关的操作") @RestController public class UserController { }
@ApiOperation	描述一个方法的功能（如 GET、POST 请求）。	value：方法简短描述 notes：方法详细描述 response：返回值类型	java @ApiOperation(value = "获取用户列表", notes = "返回所有用户的详细信息") @GetMapping public List<User> getUsers() { }
@ApiResponses	定义方法可能的响应结果集合。	无（内部包含多个 @ApiResponse）	java @ApiResponses({ @ApiResponse(code = 200, message = "成功"), @ApiResponse(code = 400, message = "参数错误") }) @PostMapping public ResponseEntity<User> createUser(@RequestBody User user) { }
@ApiResponse	描述单个响应结果。	code：HTTP 状态码 message：响应描述 response：响应数据类型	java @ApiResponse(code = 200, message = "成功创建用户", response = User.class)
@ApiParam	描述方法参数的含义。	name：参数名称 value：参数描述 required：是否必填 example：示例值	java @ApiParam(name = "id", value = "用户 ID", required = true, example = "1") @PathVariable Long id
@ApiImplicitParams	描述非显式声明的参数（如查询参数、表单参数等）。	无（内部包含多个 @ApiImplicitParam）	java @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "用户名", paramType = "query", dataType = "string") }) @GetMapping("/search") public List<User> searchUsers(@RequestParam String name) { }
@ApiImplicitParam	描述单个非显式声明的参数。	name：参数名称 value：参数描述 paramType：参数类型（如 path、query、header 等） dataType：数据类型	java @ApiImplicitParam(name = "id", value = "用户 ID", paramType = "path", dataType = "long")
@ApiModel	描述实体类的模型信息。	value：模型名称 description：模型描述	java @ApiModel(value = "用户模型", description = "用户的基本信息") public class User { }
@ApiModelProperty	描述实体类中字段的信息。	value：字段描述 example：字段示例值 required：是否必填 hidden：是否隐藏该字段	java @ApiModelProperty(value = "用户名", example = "John Doe", required = true) private String name;
@ApiIgnore	忽略某个类、方法或参数，不将其包含在生成的文档中。	无	java @ApiIgnore @GetMapping("/internal") public String internalEndpoint() { return "Ignored"; }

---

7、OpenAPI 3.0+ 对应注解

如果你使用的是 OpenAPI 3.0+（如 Springdoc），可以使用以下标准注解替代 Swagger 特有的注解：

Swagger 注解	OpenAPI 3.0+ 替代注解	说明
@ApiOperation	@Operation	描述方法功能，支持更丰富的元信息。
@ApiParam	@Parameter	描述方法参数，支持更多参数类型（如 in 属性指定参数位置）。
@ApiModel	@Schema	描述实体类模型，支持嵌套对象和复杂类型定义。
@ApiModelProperty	@Schema	描述实体类字段，支持更细粒度的约束（如 maxLength、minLength 等）。
@ApiResponse	@ApiResponse	描述响应结果，支持更复杂的响应结构（如 content 属性定义响应体格式）。

---

8、swagger2和swagger3对比总结

• Swagger 注解：适用于 Swagger 2.x 和 OpenAPI 2.0，广泛用于 Springfox。
• OpenAPI 注解：适用于 OpenAPI 3.0+，推荐用于 Springdoc 或其他现代化工具。
• 根据项目需求选择合适的注解集，能够帮助你生成清晰、易读的 API 文档。