Tags Best Practices in OpenAPI

The blog post provides a comprehensive guide on using tags in OpenAPI to organize API endpoints into groups, enhancing user comprehension. It explains that each API feature, called an endpoint, can be represented by operations such as GET or POST applied to specific paths, which are hierarchical and might limit user navigation. Tags, in contrast, allow endpoints to be categorized in multiple ways, improving documentation accessibility. The article uses a jazz club API example with endpoints for playing music, stopping music, and ordering drinks, tagged under "Music" and "Drinks." It highlights the flexibility of tags to group operations in documentation and mentions the potential use of externalDocs for additional information without overcrowding the schema. The post also briefly mentions how Speakeasy can split SDKs and documentation based on tags, with an option to customize grouping via the x-speakeasy-group field. The conclusion summarizes key tagging guidelines, including their optional nature, the requirement for unique tag names, and the allowance of CommonMark syntax in descriptions.