Tags and External Documentation in OpenAPI

In this tutorial, you will learn about Tags and External Documentation in OpenAPI. We cover key concepts, practical examples, and best practices to help you master this topic.

Tags in OpenAPI group related operations for documentation navigation, while externalDocs provides links to supplementary guides, tutorials, and reference materials outside the spec.

What You'll Learn

You will learn how to define tags with descriptions and external docs, apply tags to operations, and use the top-level externalDocs field.

flowchart LR
  A[Tags] --> B[Grouping]
  A --> C[Navigation]
  A --> D[External Links]
  B:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Defining Tags

tags:
  - name: Users
    description: User account management operations
    externalDocs:
      description: User management guide
      url: https://docs.dodatech.com/guides/users
  - name: Documents
    description: Document storage and retrieval
  - name: Authentication
    description: Login, registration, and token management

Applying Tags to Operations

paths:
  /users:
    get:
      tags:
        - Users
      summary: List all users
  /auth/login:
    post:
      tags:
        - Authentication
      summary: Authenticate user
  /documents:
    get:
      tags:
        - Documents

External Docs

externalDocs:
  description: Complete DodaTech API documentation portal
  url: https://docs.dodatech.com

Common Mistakes

1. No tag definitions — Using tags without defining them in the top-level tags array.
2. Inconsistent tag naming — Users vs User vs user-management.
3. Too many tags — Every operation gets its own tag.
4. No descriptions — Tags without descriptions in documentation.

Practice Questions

1. What is the purpose of tags?
2. How do you define tags with external docs?
3. How do you apply tags to operations?
4. What is the top-level externalDocs for?

Challenge

Create a tag organization for a CMS API with tags for Articles, Categories, Tags, Comments, Users, Media, and Settings. Include descriptions and external docs links for each.

What's Next

In the next lesson, you will learn about callbacks in OpenAPI.