tags object provides a way to group the paths (endpoints) in the Swagger UI display.
Here’s an example of the
tags object for our Mashape Weather API:
tags: - name: Air Quality description: The pollution quality of the air. - name: Weather Forecast description: A full list of details about the current weather.
In this simple weather API, there are two tags. You can list both the
name and a
description for each tag.
tags object at the root level should comprehensively list all tags used within the operation objects at each path.
For example, in the operations object for the
/weather path, we used the tag
paths: ... /weather: get: servers: - url: https://simple-weather.p.mashape.com tags: - Weather Forecast ...
We used the same tag with the
paths: ... /weatherdata: get: tags: - Weather Forecast summary: getWeatherData description: Get weather forecast with lots of details operationId: GetWeatherData
All paths that have the same tag are grouped together in the display. For example, paths that have the
Weather Forecast tag will be grouped together under the title
Weather Forecast. Each group title is a collapsible/expandable toggle. The
/aqi path has the
Air Quality tag.
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 this simple weather API, tags don’t seem all that necessary. 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.
63/92 pages complete. Only 29 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.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson