---
title: "Step 7: The tags object (OpenAPI tutorial)"
date: 2026-10-13
description: "Download PDF The tags object allows you to arrange the paths (endpoints) into named groups in the Swagger UI display. ..."
canonical_url: https://idratherbewriting.com/learnapidoc/pubapis_openapi_step7_tags_object
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# Step 7: The tags object (OpenAPI tutorial)

[STEP 1:openapi object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step1_openapi_object.html)

→

[STEP 2:info object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step2_info_object.html)

→

[STEP 3:servers object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step3_servers_object.html)

→

[STEP 4: paths object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html)

→

[STEP 5:components object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step5_components_object.html)

→

[STEP 6:security object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step6_security_object.html)

→

[STEP 7:tags object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step7_tags_object.html)

→

[STEP 8:externalDocs object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step8_externaldocs_object.html)

→

[STEP 9:Other elements](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step9_other_elements.html)

[Download PDF](https://www.buymeacoffee.com/learnapidoc/e/146076)

The `tags` object allows you to arrange the `paths` (endpoints) into named groups in the Swagger UI display.

## Defining tags at the root level

At the root level, the [`tags` object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#tagObject) lists all the tags that are used in the [operation objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md#operationObject) (which appear within the `paths` object, as explained in [Step 4: The paths object](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html)). Here’s an example of the `tags` object for our OpenWeatherMap API:

```yaml
tags:
  - name: Current Weather Data
    description: "Get current weather details"
```

We have just one tag, but you could have as many as you want (if you have a lot of endpoints, it would make sense to create multiple tags to group them). You can list both the `name` and a `description` for each tag. The `description` appears as a subtitle for the tag name in the Swagger UI display.

If you get stuck, see the [sample OpenAPI spec here](https://idratherbewriting.com/docs/openapi_spec_and_generated_ref_docs/openapi_openweathermap.yml) for the fully working sample. This will help you spot and troubleshoot indentation or other errors.

## Tags at the path object level

The `tags` object at the root level should list all tags (groups) that you want in your API. Then in each path object under `paths`, you list the tag you want that path grouped under.

By “root level,” I mean the first level in the OpenAPI document. This level is also referred to as the global level because some object properties declared here (namely servers and security) are applied to each of the operation objects unless overridden at a lower level.

For example, in the operations object for the `/weather` path, we used the tag `Current Weather Data`:

```yaml
paths:
  /weather:
    get:
      tags:
      - Current Weather Data
```

This tag is defined at the global level, so the `/weather` path will be grouped here.

## View the Appearance in Swagger UI

Add the following to the root level of your OpenAPI document in Swagger Editor:

```yaml
tags:
  - name: Current Weather Data
    description: "Get current weather details"
```

Observe how the description appears next to the collapsed Current Weather Data section.

![Tags defined at the root level](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api/step7swaggeruiprogress.png)

All paths that have the same tag are grouped together in the display. For example, paths that have the `Current Weather Data` tag will be grouped together under the title `Current Weather Data`. Each group title is a collapsible/expandable toggle.

[![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api/openapitutorial_tags.png)](https://idratherbewriting.com/assets/files/swagger/index.html)

The order of the tags in the `tags` object at the root level determines their order in Swagger UI. Additionally, the `description` appears to the right of the tag name.

In our sample OpenAPI spec, tags don’t seem all that necessary since we’re just documenting one path/endpoint. (Additionally, I configured the [Swagger UI demo](https://idratherbewriting.com/learnapidoc/pubapis_swagger_demo.html) to expand the section by default.) But imagine if you had a robust API with 30+ paths to describe. You would certainly want to organize the paths into logical groups for users to navigate.