a5c-ai/asyncapi-docs

AsyncAPI Documentation Skill

Generate and validate documentation for event-driven APIs using the AsyncAPI specification with support for multiple messaging protocols.

Capabilities

• Parse and validate AsyncAPI 2.x and 3.x specifications
• Generate documentation from AsyncAPI specs
• Document event/message schemas
• Channel and operation documentation
• Protocol-specific binding documentation (Kafka, MQTT, WebSocket, AMQP)
• Code generator integration
• Spectral linting for AsyncAPI
• Schema validation and type generation

Usage

Invoke this skill when you need to:

• Document event-driven microservices
• Create message broker API documentation
• Generate client code from async specifications
• Validate AsyncAPI specifications
• Create interactive documentation sites

Inputs

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | specPath | string | Yes | Path to AsyncAPI specification | | outputDir | string | No | Documentation output directory | | generator | string | No | html, markdown, react (default: html) | | validate | boolean | No | Run spec validation (default: true) | | lint | boolean | No | Run Spectral linting (default: true) | | generateCode | boolean | No | Generate client/server stubs | | codeLanguage | string | No | Code generation target language |

Input Example

{
  "specPath": "./asyncapi.yaml",
  "outputDir": "docs/async",
  "generator": "html",
  "validate": true,
  "lint": true,
  "generateCode": true,
  "codeLanguage": "typescript"
}

Output Structure

docs/async/
├── index.html              # Main documentation page
├── servers.html            # Server/broker documentation
├── channels/
│   ├── user-events.html    # Channel documentation
│   └── order-events.html
├── messages/
│   ├── UserCreated.html    # Message documentation
│   └── OrderPlaced.html
├── schemas/
│   ├── User.html           # Schema documentation
│   └── Order.html
├── bindings/               # Protocol bindings
│   └── kafka.html
├── search.json             # Search index
└── asyncapi.json           # Bundled spec

AsyncAPI Specification Patterns

Basic AsyncAPI 3.0 Document

asyncapi: 3.0.0
info:
  title: User Events API
  version: 1.0.0
  description: |
    Event-driven API for user management operations.

    ## Overview
    This API publishes events when user data changes.
    Consumers can subscribe to specific channels to receive
    real-time updates.

    ## Authentication
    All connections require a valid API key passed in the
    connection headers.
  contact:
    name: API Team
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  production:
    host: kafka.example.com:9092
    protocol: kafka
    description: Production Kafka cluster
    security:
      - $ref: '#/components/securitySchemes/sasl'
    tags:
      - name: production
        description: Production environment

  staging:
    host: kafka-staging.example.com:9092
    protocol: kafka
    description: Staging environment

channels:
  userCreated:
    address: user.events.created
    messages:
      UserCreatedMessage:
        $ref: '#/components/messages/UserCreated'
    description: |
      Published when a new user account is created.

      **Trigger**: User registration completion
      **Frequency**: ~1000 events/day

  userUpdated:
    address: user.events.updated
    messages:
      UserUpdatedMessage:
        $ref: '#/components/messages/UserUpdated'

operations:
  publishUserCreated:
    action: send
    channel:
      $ref: '#/channels/userCreated'
    summary: Publish user created event
    description: |
      Publishes an event when a new user is created.
      Events are partitioned by user ID.
    tags:
      - name: users
    bindings:
      kafka:
        groupId: user-service
        clientId: user-publisher

  subscribeUserCreated:
    action: receive
    channel:
      $ref: '#/channels/userCreated'
    summary: Subscribe to user created events
    description: |
      Subscribe to receive notifications when new users
      are created. Ideal for:
      - Welcome email services
      - Analytics tracking
      - Audit logging

components:
  messages:
    UserCreated:
      name: UserCreated
      title: User Created Event
      summary: Event published when a user is created
      contentType: application/json
      traits:
        - $ref: '#/components/messageTraits/commonHeaders'
      payload:
        $ref: '#/components/schemas/UserCreatedPayload'
      examples:
        - name: NewUser
          summary: Standard user creation
          payload:
            userId: "usr_123456"
            email: "[email protected]"
            createdAt: "2026-01-24T10:30:00Z"
            source: "web-signup"

    UserUpdated:
      name: UserUpdated
      title: User Updated Event
      summary: Event published when user data changes
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserUpdatedPayload'

  schemas:
    UserCreatedPayload:
      type: object
      description: Payload for user created events
      required:
        - userId
        - email
        - createdAt
      properties:
        userId:
          type: string
          description: Unique user identifier
          pattern: "^usr_[a-zA-Z0-9]+$"
          examples:
            - "usr_123456"
        email:
          type: string
          format: email
          description: User's email address
        createdAt:
          type: string
          format: date-time
          description: Timestamp of user creation
        source:
          type: string
          enum:
            - web-signup
            - mobile-app
            - admin-portal
            - api
          description: Registration source

    UserUpdatedPayload:
      type: object
      required:
        - userId
        - updatedAt
        - changes
      properties:
        userId:
          type: string
          description: Unique user identifier
        updatedAt:
          type: string
          format: date-time
        changes:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              oldValue:
                type: string
              newValue:
                type: string

  messageTraits:
    commonHeaders:
      headers:
        type: object
        properties:
          correlationId:
            type: string
            description: Correlation ID for distributed tracing
            format: uuid
          timestamp:
            type: string
            format: date-time
            description: Event timestamp
          version:
            type: string
            description: Schema version

  securitySchemes:
    sasl:
      type: scramSha256
      description: SASL/SCRAM-SHA-256 authentication

Kafka-Specific Bindings

channels:
  orderEvents:
    address: orders.events
    bindings:
      kafka:
        topic: orders.events.v1
        partitions: 12
        replicas: 3
        topicConfiguration:
          cleanup.policy:
            - delete
          retention.ms: 604800000  # 7 days
          segment.bytes: 1073741824
    messages:
      OrderCreated:
        bindings:
          kafka:
            key:
              type: string
              description: Order ID used as partition key
            schemaIdLocation: header
            schemaIdPayloadEncoding: confluent

WebSocket Channel

asyncapi: 3.0.0
info:
  title: Real-time Notifications API
  version: 1.0.0

servers:
  production:
    host: ws.example.com
    protocol: wss
    description: WebSocket server for real-time notifications

channels:
  notifications:
    address: /notifications/{userId}
    parameters:
      userId:
        description: The user ID to receive notifications for
    messages:
      Notification:
        $ref: '#/components/messages/Notification'
    bindings:
      ws:
        query:
          type: object
          properties:
            token:
              type: string
              description: Authentication token
          required:
            - token

MQTT Channel

asyncapi: 3.0.0
info:
  title: IoT Sensor API
  version: 1.0.0

servers:
  production:
    host: mqtt.example.com:8883
    protocol: mqtts
    description: MQTT broker for IoT devices

channels:
  sensorReadings:
    address: sensors/{sensorId}/readings
    parameters:
      sensorId:
        description: Unique sensor identifier
    messages:
      SensorReading:
        $ref: '#/components/messages/SensorReading'
    bindings:
      mqtt:
        qos: 1
        retain: false
        bindingVersion: '0.2.0'

AsyncAPI CLI Commands

Validation

# Validate specification
asyncapi validate asyncapi.yaml

# Validate with custom rules
asyncapi validate asyncapi.yaml --rule-file .spectral.yaml

Documentation Generation

# Generate HTML documentation
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o docs

# Generate Markdown
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/markdown-template -o docs

# Generate React app
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/react-component -o docs

Code Generation

# TypeScript types
asyncapi generate models asyncapi.yaml typescript -o src/types

# Java models
asyncapi generate models asyncapi.yaml java -o src/main/java

# Python models
asyncapi generate models asyncapi.yaml python -o src/models

Spectral Linting Rules

.spectral.yaml

extends:
  - "@asyncapi/spectral-ruleset"

rules:
  # Require descriptions
  asyncapi-info-description: error
  asyncapi-channel-description: warn
  asyncapi-operation-description: warn

  # Require examples
  asyncapi-message-examples: warn

  # Schema validation
  asyncapi-payload-unsupported-schemaFormat: error
  asyncapi-schema: error

  # Custom rules
  operation-summary-required:
    description: Operations must have summaries
    given: "$.operations[*]"
    then:
      field: summary
      function: truthy
    severity: warn

  message-content-type:
    description: Messages must specify content type
    given: "$.components.messages[*]"
    then:
      field: contentType
      function: truthy
    severity: error

Documentation Best Practices

Channel Documentation

channels:
  paymentCompleted:
    address: payments.completed.v1
    description: |
      ## Payment Completed Events

      Published when a payment is successfully processed.

      ### Use Cases
      - Order fulfillment initiation
      - Customer notification
      - Financial reconciliation

      ### Consumer Guidelines
      - Process events idempotently (use `paymentId` for deduplication)
      - Acknowledge within 30 seconds
      - Implement dead letter queue handling

      ### SLA
      - **Latency**: Events published within 1s of payment completion
      - **Ordering**: Events are ordered by `paymentId` within partition
      - **Retention**: 7 days

Schema Documentation

components:
  schemas:
    Payment:
      type: object
      title: Payment
      description: |
        Represents a completed payment transaction.

        ## Versioning
        This schema follows semantic versioning. Breaking changes
        will result in a new major version.

        ## Privacy
        Contains PII - handle according to data protection policies.
      required:
        - paymentId
        - amount
        - currency
      properties:
        paymentId:
          type: string
          format: uuid
          description: Unique payment identifier
          x-field-extra-annotation: "@Id"
        amount:
          type: number
          format: decimal
          description: Payment amount in minor units (cents)
          minimum: 0
          examples:
            - 1999
            - 50000
        currency:
          type: string
          pattern: "^[A-Z]{3}$"
          description: ISO 4217 currency code
          examples:
            - USD
            - EUR
            - GBP

Workflow

1. Parse specification - Load and validate AsyncAPI document
2. Lint specification - Run Spectral rules
3. Validate schemas - Check JSON Schema validity
4. Generate documentation - Create HTML/Markdown output
5. Generate code - Create typed models (optional)
6. Bundle specification - Create bundled output file

Dependencies

{
  "devDependencies": {
    "@asyncapi/cli": "^1.0.0",
    "@asyncapi/html-template": "^2.0.0",
    "@asyncapi/markdown-template": "^1.0.0",
    "@asyncapi/generator": "^1.0.0",
    "@asyncapi/modelina": "^3.0.0",
    "@stoplight/spectral-cli": "^6.0.0",
    "@asyncapi/spectral-ruleset": "^1.0.0"
  }
}

Best Practices Applied

• Use semantic versioning in spec info
• Document all channels with descriptions
• Include message examples
• Specify content types for messages
• Use traits for common patterns
• Document protocol-specific bindings
• Include consumer guidelines
• Define SLAs in documentation

References

• AsyncAPI Specification: https://www.asyncapi.com/docs/reference/specification/v3.0.0
• AsyncAPI CLI: https://www.asyncapi.com/tools/cli
• AsyncAPI Generator: https://www.asyncapi.com/tools/generator
• AsyncAPI Modelina: https://www.asyncapi.com/tools/modelina
• Spectral: https://stoplight.io/open-source/spectral

Target Processes

• api-doc-generation.js
• api-reference-docs.js
• data-model-docs.js
• docs-as-code-pipeline.js