Tags in OpenAPI are optional but very useful! If you use Speccy then it has Opinions(TM) and will suggest that you need tags on every endpoint. The formal definition doesn’t require it however and I tend to turn off these rules for small APIs.
When tags really come into their own is on larger APIs, perhaps an application only has one API and everything goes there – or there is one “utility” API that’s a catchall for anything not important or big enough to need its own API. Using tags on these larger APIs can really help users to find their way around.
Adding Tags to an OpenAPI Spec
To add a tag to your OpenAPI spec, you need to do two things:
- Define the tags in a top-level
- Add a tag to each operation in the spec
tags element looks something like this:
- name: Account
description: Relating to an account (the user must have access to the account)
- name: User
description: Manage a user account (either your own, or one you have permissions to access)
- name: Admin
description: Only available to superusers
I’d recommend adding descriptions here, it helps to make it clearer both to developers and to future maintainers of the API and its description what the tag was intended for.
Then to add the tag to a path, the
tags array goes at the same level as
operationID, like this (remember you can add as many tags as make sense):
summary: Retrieve API Secrets
Quite a few of the documentation tools (including ReDoc which is my personal favourite) will render the endpoints grouped by tag which is very valuable. Speccy recommends having the tags alphabetically but I tend to turn this rule off where alphabetical doesn’t make sense (for example above where I have a few endpoints tagged “Admin” but most users can’t access those so I have it last in the list).
Using tags can be a valuable addition to your OpenAPI spec so I hope that sharing this example is helpful!