Step 7: The tags object (OpenAPI tutorial)
tags object provides a way to group the paths (endpoints) in the Swagger UI display.
Defining tags at the root level
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
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 used the same tag
paths: /weather: get: tags: - Current Weather Data
How tags appear in Swagger UI
All paths that have the same tag are grouped together in the display. For example, paths that have the
Weather tag will be grouped together under the title
Weather. 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 display 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.
65/96 pages complete. Only 31 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.