Search results

Step 7: The tags object (OpenAPI tutorial)

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

The tags object provides a way to group the paths (endpoints) in the Swagger UI display.

Defining tags at the root level

At the root level, the tags object lists all the tags that are used in the operation objects (which appear within the paths object, as explained in step 4).

Here’s an example of the tags object for our OpenWeatherMap API:

tags:
  - name: Current Weather Data
    description: "Get current weather details"

We just have one tag, but you could have as many as you want (if you have a lot of endpoints, it would make sense to create multiple tags to group them). You can list both the name and a description for each tag. The description appears as a subtitle for the tag name.

Tags at the path object level

The tags object at the root level should comprehensively list all tags used within the operation objects at each path. Then in each path, you list the tag you want that path grouped under.

For example, in the operations object for the /current path, we already used the same tag Current Weather Data:

paths:
  /weather:
    get:
      tags:
      - Current Weather Data

Appearance in Swagger UI

Activity

Add the following to the root level of your OpenAPI document in Swagger Editor:

tags:
  - name: Current Weather Data
    description: "Get current weather details"

Observe how the description appears next to the collapsed Current Weather Data section.

Tags defined at the root level
Tags defined at the root level

All paths that have the same tag are grouped together in the display. For example, paths that have the Current Weather Data tag will be grouped together under the title Current Weather Data. Each group title is a collapsible/expandable toggle.

The order of the tags in the tags object at the root level determines their order in Swagger UI. Additionally, the descriptions appear to the right of the tag name.

In our sample OpenAPI spec, tags don’t seem all that necessary since we’re just documenting one path/endpoint. (Additionally, I configured the Swagger UI demo to expand the section by default.) But imagine if you had a robust API with 30+ paths to describe. You would certainly want to organize the paths into logical groups for users to navigate.

64% Complete

64/108 pages complete. Only 44 more pages to go...

Donate?

Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers