OpenAPI & AsyncAPI 标签指南：高效组织与优化API文档

一. 标签在API文档中的作用

在现代 API 开发中，清晰的文档对于开发者协作和使用至关重要。OpenAPI 和 AsyncAPI 是编写 API 合约的两种开源规范，它们不仅描述了端点、数据结构和安全约束，还通过标签（Tags）功能帮助开发者高效组织和分类 API 端点。

二. 使用标签组织API端点的示例

在 API 合约中，标签用于按业务功能或逻辑对象对相关端点进行分组。通过在文档根位置定义标签数组，可为 API 端点赋予清晰的分类结构：

tags:
  - name: Users
    description: Operations related to user management
  - name: Orders
    description: Operations related to order processing

定义标签后，可在端点中使用 tags 属性进行归类：

paths:
  /users:
    get:
      tags:
        - Users
  /orders:
    post:
      tags:
        - Orders

提示：单个端点可以同时应用多个标签，以便更灵活地组织文档内容。

三. 标签的优势与使用技巧

1. 提高文档可读性

标签帮助开发者快速定位相关端点，通过 description 提供额外信息：

tags:
  - name: Diffs
    description: Summarizes changes in the API

生成文档时，标签描述将直接展示，帮助用户直观理解用途。

2. 使用外部文档链接

对于复杂业务逻辑标签，可使用 externalDocs 属性指向外部文档：

tags:
  - name: Diffs
    description: Summarizes changes in the API
    externalDocs:
      description: Learn more about Diffs
      url: https://example.com/diffs

文档中会显示跳转链接，方便开发者获取详细信息。

3. 标签排序的重要性

在根标签数组中定义的顺序会影响生成文档中端点组的显示顺序：

tags:
  - name: Users
  - name: Orders

生成文档时，端点组将按此顺序展示，确保文档逻辑一致性。

四. 使用标签的最佳实践

1. 标记所有端点

确保每个端点至少分配一个标签，包括单一端点：

paths:
  /health:
    get:
      tags:
        - HealthCheck

未标记端点可能在生成文档时被遗漏，影响文档完整性。

2. 避免重复标签

每个标签名称应唯一，避免混淆：

tags:
  - name: Validations
    description: Validation-related operations

不要重复定义名称不同描述的标签，这会让用户难以判断端点所属分类。

3. 确保标签定义完整

未在根标签对象中定义的标签可能导致排序问题：

tags:
  - name: Users
  - name: Orders

如果某些端点使用未定义的标签（如 Previews 或 Ping），它们将在文档末尾显示，影响逻辑性。因此建议完整定义所有标签。

五. 总结

合理使用 OpenAPI 和 AsyncAPI 标签，可显著提升 API 文档的组织性和可读性。标签不仅帮助快速定位端点，还能通过描述和外部文档链接提供上下文信息。遵循最佳实践（标记所有端点、避免重复标签、完整定义标签）将进一步提升文档质量和开发者体验。

通过这些方法，您可以创建清晰、易于维护的 API 文档，为开发者提供高效协作工具。

原文链接: https://bump.sh/blog/openapi-tags-organize-endpoints