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

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

Field	Type	Required	Description
`name`	String	✅	The name of the tag. *Must* be unique in the document.
`description`	String		A description of the tag. This may contain CommonMark syntax (opens in a new tab) to provide a rich description.
`externalDocs`	External Documentation Object		Additional external documentation for this tag.
`x-*`	Extensions		Any number of extension fields can be added to the tag object that can be used by tooling and vendors.

Multiple Namespaces

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