OAS 3 本指南适用于 OpenAPI 3.0。如果您使用的是 OpenAPI 2.0，请参阅我们的 OpenAPI 2.0 指南。

使用标签进行分组操作

您可以为每个 API 操作分配一个 tags 列表。带标签的操作可能会被工具和库以不同的方式处理。例如，Swagger UI 使用 tags 对显示的操作进行分组。

paths:
  /pet/findByStatus:
    get:
      summary: Finds pets by Status
      tags:
        - pets
      ...
  /pet:
    post:
      summary: Adds a new pet to the store
      tags:
        - pets
      ...
  /store/inventory:
    get:
      summary: Returns pet inventories
      tags:
        - store
      ...

您可以选择通过使用根级别的全局 tags 部分为每个标签指定 description 和 externalDocs。这里的标签名称应与操作中使用的标签名称匹配。

tags:
  - name: pets
    description: Everything about your Pets
    externalDocs:
      url: http://docs.my-api.com/pet-operations.htm
  - name: store
    description: Access to Petstore orders
    externalDocs:
      url: http://docs.my-api.com/store-orders.htm

全局标签部分中的标签顺序也控制着 Swagger UI 中的默认排序。请注意，即使在根级别没有定义标签，也可以在操作中使用该标签。

没有找到您要查找的内容？ 咨询社区
发现错误？ 告知我们