Springdoc 全部注解一文解释清楚

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

1. 核心注解

@Tag-Class类上

• 作用：为控制器或方法分组，便于组织和分类 API。

• 常用属性：

  • name：标签名称。
  • description：标签描述信息。

• 示例：

    @Tag(name = "策略库接口",description = "这是策略库的所有接口")
    @RestController
    @RequestMapping("/tacticsInfo")
    public class TacticsInfoController extends BaseController
    {
      // ...
     }
  

2. 方法级别注解

@Operation-方法描述

• 作用：描述一个 API 方法的功能。
• 常用属性：
  • summary：方法的简短描述。
  • description：方法的详细描述。
  • responses：定义可能的响应结果。
  • deprecated：标记方法是否已废弃。
• 示例：

    @Operation(summary = "查询策略库:tactics_info列表",description = "查询策略库:tactics_info列表-list接口")
    @RequiresPermissions("business:tacticsInfo:list")
    @GetMapping("/list")
    public TableDataInfo list(TacticsInfo tacticsInfo)
    {
      // ...
  }
  

@ApiResponse 和 @ApiResponses-方法的返回结果

• 作用：描述 API 方法的响应结果。
• 常用属性：
  • responseCode：HTTP 状态码。
  • description：响应描述信息。
  • content：响应的内容类型（如 JSON、XML）。
• 示例：

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

---

3. 参数相关注解

@Parameter-方法参数

• 作用：描述方法参数的含义。
• 常用属性：
  • name：参数名称。
  • description：参数描述信息。
  • required：是否必填。
  • example：参数示例值。
  • in：参数位置（如 path、query、header 等）。
• 示例：

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

@Parameters方法参数（单个）

• 作用：描述多个参数。
• 示例：

  @Operation(summary = "搜索用户")
  @Parameters({
      @Parameter(name = "name", description = "用户名", in = ParameterIn.QUERY),
      @Parameter(name = "age", description = "用户年龄", in = ParameterIn.QUERY)
  })
  @GetMapping("/search")
  public List<User> searchUsers(@RequestParam String name, @RequestParam Integer age) {
      // ...
  }
  

---

4. 实体模型相关注解

@Schema-描述实体类或字段的信息

• 作用：描述实体类或字段的信息。
• 常用属性：
  • description：模型或字段的描述信息。
  • example：字段示例值。
  • required：字段是否必填。
  • type：字段的数据类型。
  • format：字段的格式（如 date-time、email 等）。
• 示例：

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

---

5. 其他注解

@Hidden-隐藏某个类、方法或参数

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

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

---

6. 配置相关注解（不常用）

@OpenAPIDefinition-全局配置 OpenAPI 文档的元信息

• 作用：全局配置 OpenAPI 文档的元信息。这个不常用，还是常用配置文件类型的
• 常用属性：
  • info：文档的基本信息（标题、版本、描述等）。
  • tags：全局标签定义。
  • servers：API 的服务器地址。
• 示例：

  @OpenAPIDefinition(
      info = @Info(title = "用户管理系统", version = "1.0", description = "用户相关的 API 文档"),
      tags = {
          @Tag(name = "用户管理", description = "与用户相关的操作")
      },
      servers = {
          @Server(url = "http://localhost:8080", description = "本地开发环境")
      }
  )
  @SpringBootApplication
  public class Application {
      public static void main(String[] args) {
          SpringApplication.run(Application.class, args);
      }
  }
  

---

7. 总结

以下是 springdoc 常用注解的分类总结：

注解	作用
@Tag	为控制器或方法分组，便于组织和分类 API。
@Operation	描述 API 方法的功能。
@ApiResponse	描述单个响应结果。
@Parameter	描述方法参数的含义。
@Schema	描述实体类或字段的信息。
@Hidden	隐藏某个类、方法或参数，不包含在生成的文档中。
@OpenAPIDefinition	全局配置 OpenAPI 文档的元信息（标题、版本、描述等）。