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.
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 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