concept tag in category swagger

This is an excerpt from Manning's book Designing APIs with Swagger and OpenAPI MEAP V04. Login to get full access to this book.

In addition to metadata we want to organize our API documentation so that it’s a little easier to figure out what operations exist, at a glance. OpenAPI has the concept of tags and we’re going to use them to categorize our five operations into Reviews and Users to give a better overview of the API’s operations.

What happened in the last section is that we added a tag to an operation. Those tags will be created on the fly and tools (such as SwaggerEditor/SwaggerUI) can render UIs based on them. But we are missing a description for the tag, something to expand on what the tag entails. The word Reviews may not be sufficient to tell the consumer what’s going on.

After adding a description to the tags we’ll see the following rendered in SwaggerEditor…

Figure 8.9. Showing the description of the tag

To add a description to a tag we need to create a root-level tags field and describe our tags in it.