AsyncAPI Tags and External Documentation

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

Tags and external documentation enrich AsyncAPI specifications with metadata, categorization, and references to additional resources. They improve discoverability and help consumers understand the context of your event-driven APIs.

What You'll Learn

• How to define and use tags
• Tag organization best practices
• External documentation references
• Cross-referencing related resources
• Tag inheritance in AsyncAPI

Why It Matters

Well-organized tags make AsyncAPI documents easier to navigate. External documentation provides consumers with detailed guides, runbooks, and reference materials beyond the specification.

Real-World Use

A large enterprise catalogs 200+ AsyncAPI specs with standardized tags for domain (payments, orders, inventory), criticality (p0, p1, p2), and ownership (team-payments, team-orders). This enables automated documentation portals and alert routing.

Flow Chart

flowchart LR
    A[Tags] --> B[Root Level]
    A --> C[Channel Level]
    A --> D[Operation Level]
    A --> E[Message Level]
    F[External Docs] --> G[Root Level]
    F --> H[Channel Level]
    F --> I[Operation Level]
    F --> J[Message Level]
    B --> K[Global Metadata]
    C --> L[Channel Context]
    D --> M[Operation Context]
    E --> N[Message Context]

Code Examples

Example 1: Tags at Different Levels

tags:
  - name: orders
    description: Order management domain
    externalDocs:
      description: Order domain documentation
      url: https://docs.example.com/domains/orders
  - name: events
    description: Event-driven communication
  - name: p0
    description: Critical production events
  - name: team-payments
    description: Owned by payments team

channels:
  order/created:
    tags:
      - name: orders
      - name: p0
      - name: team-payments
    publish:
      tags:
        - name: order-creation
          description: Order creation flow
        - name: synchronous
      message:
        tags:
          - name: event-v1
            description: Version 1 event schema

Expected output: Tags applied at root, channel, operation, and message levels for fine-grained categorization.

Example 2: External Documentation References

info:
  title: Payment Events API
  version: '2.0.0'
  description: Event-driven payment processing
  externalDocs:
    description: Payment event reference
    url: https://docs.example.com/payments/events

servers:
  production:
    url: kafka://payments.example.com:9092
    protocol: kafka
    description: Production payment events
    externalDocs:
      description: Production deployment guide
      url: https://docs.example.com/deploy/payments

channels:
  payment/authorized:
    description: Payment authorization events
    externalDocs:
      description: Payment auth flow documentation
      url: https://docs.example.com/flows/payment-auth
    publish:
      externalDocs:
        description: How to emit payment events
        url: https://docs.example.com/guides/emit-payments
      message:
        externalDocs:
          description: Payment event schema reference
          url: https://docs.example.com/schemas/payment-event

Expected output: External documentation references at every level, providing context-specific links for readers.

Example 3: Tag-Based Organization for Documentation Portal

tags:
  - name: domain:orders
    description: Order management
    externalDocs:
      url: https://wiki.example.com/domains/orders
  - name: domain:payments
    description: Payment processing
  - name: domain:inventory
    description: Inventory management
  - name: criticality:critical
    description: Events that require immediate attention
  - name: criticality:normal
    description: Standard operational events
  - name: team:alpha
    description: Alpha team ownership
    externalDocs:
      url: https://team-alpha.example.com
  - name: team:beta
    description: Beta team ownership

channels:
  order/created:
    tags:
      - name: domain:orders
      - name: criticality:critical
      - name: team:alpha
  payment/settled:
    tags:
      - name: domain:payments
      - name: criticality:critical
      - name: team:alpha
  inventory/updated:
    tags:
      - name: domain:inventory
      - name: criticality:normal
      - name: team:beta

Expected output: Structured tags with a convention (domain:xxx, criticality:xxx, team:xxx) that enables automated filtering in documentation portals.

Common Mistakes

Practice Questions

1. What is the difference between tags at root level and tags on channels?
2. How do external documentation references enhance an AsyncAPI specification?
3. What tagging conventions work well for large organizations?
4. Can tags be inherited from parent to child elements?
5. How do documentation generators use tags?

Challenge

Design a tagging Strategy for a financial services company with 50+ event-driven services. Create tags for domain, subdomain, criticality, team ownership, data classification, and Compliance requirements. Show how these tags organize events in a documentation portal.

FAQ

Mini Project

Build a tagging taxonomy for a healthcare event platform. Include tags for HIPAA compliance, PHI data handling, team ownership, deployment regions, and event criticality. Generate a documentation portal mockup showing how tags filter and organize 30+ event channels.

What's Next

Learn about code generation from AsyncAPI specs