Grouping Operations With Tags

You can assign a list of tags to each API operation. Tagged operations may be handled differently by tools and libraries. For example, Swagger UI uses tags to group the displayed operations.

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

Optionally, you can specify description and externalDocs for each tag by using the global tags section on the root level. The tag names here should match those used in operations.

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

The tag order in the global tags section also controls the default sorting in Swagger UI. Note that it is possible to use a tag in an operation even if it is not defined on the root level.

Did not find what you were looking for? Ask the community
Found a mistake? Let us know