使用标签对操作进行分组

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

1
paths:
2
  /pet/findByStatus:
3
    get:
4
      summary: Finds pets by Status
5
      tags:
6
        - pets
7
      ...
8
  /pet:
9
    post:
10
      summary: Adds a new pet to the store
11
      tags:
12
        - pets
13
      ...
14
  /store/inventory:
15
    get:
16
      summary: Returns pet inventories
17
      tags:
18
        - store
19
      ...

OpenAPI tags in Swagger UI

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

1
tags:
2
  - name: pets
3
    description: Everything about your Pets
4
    externalDocs:
5
      url: http://docs.my-api.com/pet-operations.htm
6
  - name: store
7
    description: Access to Petstore orders
8
    externalDocs:
9
      url: http://docs.my-api.com/store-orders.htm

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

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