Getting to know a new API is always daunting, but for the larger APIs, the hardest part is knowing where to start. Help users find their way with your API by adding tags to your OpenAPI endpoints. Tags give additional context by grouping endpoints together to emphasize the main focus of each one.

How to use tags in OpenAPI

Using tags in an OpenAPI description requires the following two-steps:

1. Declare the tag at the top level of the OpenAPI description.
2. Add the tag to the endpoints that belong in it.

As an example, take a look at the Museum Example API. Its tags section looks like the following:

tags:
  - name: Operations
    description: Operational information about the museum.
  - name: Events
    description: Special events hosted by the Museum.
  - name: Tickets
    description: Museum tickets for general entrance or special events.

Each endpoint has the tag or tags that relate to it. Still with the museum example, here's the first few lines of the endpoint that returns a list of special events going on at the museum:

  /special-events:
    post:
      summary: Create special events
      description: Creates a new special event for the museum.
      operationId: createSpecialEvent
      tags:
        - Events

The tags field of an operation is an array, so you can add multiple tags to any operation to indicate different things.

OpenAPI tags and tag extensions

A very visible effect of good tag usage in an OpenAPI description is that most documentation tools use tags as navigation groups. For instance, the museum example from earlier produces output like the following:

Already you have seen the value that tags can bring to an OpenAPI description, introducing order and supporting user discovery of related endpoints. There are also some widely-used extensions that can make an even better experience. We'll look at two in particular: x-tagGroups and x-displayName.

Since tags in OpenAPI 3.x do not have a summary field, usually the tag name is used for display. x-displayName lets the user add a more human-readable label to a tag. If we extend the Museum API example, we can add some display names to the tag block, like the following example:

tags:
  - name: Operations
    x-displayName: About the museum
    description: Operational information about the museum.
  - name: Events
    x-displayName: Upcoming events
    description: Special events hosted by the Museum.
  - name: Tickets
    x-displayName: Buy tickets
    description: Museum tickets for general entrance or special events.

The changes are reflected in the documentation, with the navigation sections using this new data as seen in the following screenshot:

The other nice extension for tags that was mentioned earlier is x-tagGroups. As the name implies, it's a way of grouping tags; this approach is ideal for very large APIs where a single level of categorizing isn't enough. The Museum API isn't really large enough to need x-tagGroups, but it can work as an example to illustrate the idea in action.

x-tagGroups is a new top-level OpenAPI addition, where the groups are listed, and tags from the tags section are added into the groups. The following shows an example of x-tagGroups that could be used with the existing tags in the Museum API:

x-tagGroups:
  - name: Plan your visit
    tags:
      - Operations
      - Events
  - name: Purchases
    tags:
      - Tickets

This addition is useful for all sorts of tools, but again can be seen in the documentation output. The following screenshot shows how the same API reference documentation looks with the tag groups in place:

These additions are supported by Redocly tooling and others, and can give an extra level of context to the users of your API that can prove very valuable.

Take your OpenAPI tags to the next level

Check your OpenAPI descriptions and see if you are taking advantage of tags and their related extensions. Using tags to group the endpoints in your API is useful beyond producing user-friendly documentation. Many code generation tools such as SDK generators may use this information to group functionality into modules. You can also publish reduced versions of your API description, filtering by tag.

Ready for more? You might find some of these suggestions interesting as your next read:

• Documentation for x-tagGroups.
• Documentation for x-displayName.
• Publish OpenAPI descriptions without internal endpoints.
• Use Operation IDs for better API design.