asyncapi-docs

name	asyncapi-docs
description	AsyncAPI specification handling for event-driven API documentation. Parse, validate, and generate documentation for message-based APIs including Kafka, MQTT, WebSocket, and AMQP systems.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
backlog-id	SK-016
metadata	{"author":"babysitter-sdk","version":"1.0.0"}
graph	{"domains":["domain:software-engineering"],"specializations":["specialization:technical-documentation"],"skillAreas":["skill-area:api-doc-generation","skill-area:reference-docs"],"roles":["role:technical-writer","role:documentation-engineer"]}

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: [e-mail]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0


  
     
     
       
    
        
    
        
          

  
     
     
      


  
     
    
      
         
     
         
        

  
     
    
      
         


  
     
    
       
        
         
        
    
      
         
         

  
     
    
       
         
     

  
    
       
         
             
       
      
          
      
         
      
          
             
          
             
             
             
             

    
       
         
            
       
      
         

  
    
       
           
      
         
         
         
      
        
           
             
           
          
             
        
           
           
             
        
           
           
              
        
           
          
             
             
             
             
            

    
       
      
         
         
         
      
        
           
             
        
           
           
        
           
          
             
            
              
                 
              
                 
              
                 

  
    
      
         
        
          
             
                 
             
          
             
             
              
          
             
              

  
    
       
        

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:
            - 

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
      -        
         

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:
           
           
                
           
          
             
             
        
           
           
             
          
             
             
             

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