Springdoc 全部注解一文解释清楚

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

1. 核心注解

@Tag-Class类上

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

• 常用属性：

  • name：标签名称。
  • description：标签描述信息。
  • externalDocs：外部文档链接（@ExternalDocumentation 类型）。

• 示例：

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

通过@Tag 的 name 属性进行分组排序

注：springdoc 本身并没有提供直接用于排序的注解，但可以通过以下方式实现对 API 文档的排序

• 在生成的 OpenAPI 文档中，@Tag 的 name 属性会影响分组的顺序。按字母顺序排列。
• 如果需要自定义顺序，可以在 name 中添加前缀（如数字）来控制顺序。

@Tag(name = "1. User", description = "用户相关操作")
@RestController
@RequestMapping("/users")
public class UserController { }

@Tag(name = "2. Order", description = "订单相关操作")
@RestController
@RequestMapping("/orders")
public class OrderController { }

2. 方法级别注解

@Operation-方法描述

• 作用：描述一个 API 方法的功能。
• 常用属性：
  • summary：操作的简短描述。
  • description：操作的详细描述。
  • tags：所属的标签（数组）。
  • operationId：唯一标识符，用于区分不同的操作。
  • responses：定义响应信息（@ApiResponse 类型）。
  • parameters：定义请求参数（@Parameter 类型）。
  • requestBody：定义请求体（@RequestBody 类型）。
  • deprecated：是否标记为已废弃（布尔值）。
  • security：定义安全要求（@SecurityRequirement 类型）。
  • hidden：是否隐藏该操作（布尔值）。
• 示例：

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

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

• 作用：描述 API 方法的响应结果。
• 常用属性：
  • responseCode：HTTP 响应码（如 “200”、“404”）。
  • description：响应的描述信息。
  • content：响应的内容类型（@Content 类型）。
  • headers：响应头信息（@Header 类型）。
  • links：链接信息（@Link 类型）。
• 示例：

  @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方法参数（单个）

• 作用：描述多个参数。
• 常用属性：
  • name：参数名称。
  • description：参数的描述信息。
  • in：参数的位置（如 “query”、“path”、“header”、“cookie”）。
  • required：是否为必填参数（布尔值）。
  • schema：参数的数据类型（@Schema 类型）。
  • example：示例值。
  • deprecated：是否标记为已废弃（布尔值）。
• 示例：

  @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) {
      // ...
  }
  

@RequestBody

• 作用：用于描述 API 的请求体。
• 常用属性
  • description：请求体的描述信息。
  • content：请求体的内容类型（@Content 类型）。
  • required：是否为必填请求体（布尔值）。
• 示例

@RequestBody(
    description = "User object to be created",
    required = true,
    content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))
)

---

4. 实体模型相关注解

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

• 作用：描述实体类或字段的信息。
• 常用属性：
  • type：字段的数据类型（如 “string”、“integer”、“array”）。
  • format：字段的格式（如 “date-time”、“int64”）。
  • description：字段的描述信息。
  • example：字段的示例值。
  • defaultValue：字段的默认值。
  • required：是否为必填字段（布尔值）。
  • deprecated：是否标记为已废弃（布尔值）。
  • enum：枚举值列表。
  • implementation：指定类作为模型（仅用于复杂对象）。
• 示例：

  @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 的服务器地址。
  • externalDocs：外部文档链接（@ExternalDocumentation 类型）。
• 示例：

  @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. 数据模型相关注解

@ArraySchema-用于描述数组类型的字段。

• 参数

  • array：数组的元素类型（@Schema 类型）。
  • uniqueItems：是否唯一（布尔值）。
  • minItems：最小元素数量。
  • maxItems：最大元素数量。

• 示例

@ArraySchema(
    array = @Schema(type = "string"),
    uniqueItems = true,
    minItems = 1,
    maxItems = 10
)
private List<String> tags;

---

@Xml-用于描述 XML 相关的元数据。

• 参数

  • name：XML 元素名称。
  • namespace：XML 命名空间。
  • prefix：XML 前缀。
  • attribute：是否为属性（布尔值）。

• 示例

@Xml(name = "user", namespace = "http://example.com/user")
private User user;

---

7. 总结

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

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