OpenAPI
Tags

OpenAPI Tags

The document-level tags field contains a list of tag definitions that may be used to categorize or group operations in the API. Tags can be referenced by operations via the operations-level tags field.

Tag definitions at the document level are optional, even if an undefined tag is referenced in an operation, but it is recommended that all tags used are defined here to provide useful documentation and intent for the tags.

Tag names must be unique in the document.

Example:


tags:
- name: drinks
description: The drinks endpoints.
- name: authentication
description: The authentication endpoints.

Tag Object in OpenAPI

A Tag Object defines a single tag that can be used to categorize or group operations in the API.

FieldTypeRequiredDescription
nameStringThe name of the tag. Must be unique in the document.
descriptionStringA description of the tag. This may contain CommonMark syntax (opens in a new tab) to provide a rich description.
externalDocsExternal Documentation ObjectAdditional external documentation for this tag.
x-*ExtensionsAny number of extension fields can be added to the tag object that can be used by tooling and vendors.

Multiple Namespaces in OpenAPI

If you want to add a method to multiple namespaces, list multiple values in tags. It accepts an array of values:


paths:
/drinks:
get:
operationId: listDrinks
tags:
- drinks
- beverages