Agent skill

asyncapi-docs

AsyncAPI specification handling for event-driven API documentation. Parse, validate, and generate documentation for message-based APIs including Kafka, MQTT, WebSocket, and AMQP systems.

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/technical-documentation/skills/asyncapi-docs

Metadata

Additional technical details for this skill

author
babysitter-sdk
version
1.0.0

SKILL.md

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

json
{
  "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

yaml
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: api-team@example.com
  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: "john@example.com"
            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

yaml
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

yaml
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

yaml
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

bash
# Validate specification
asyncapi validate asyncapi.yaml

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

Documentation Generation

bash
# 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

bash
# 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

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

yaml
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

yaml
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

json
{
  "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

Target Processes

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31
Explore
a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31
Explore
a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31
Explore
a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31
Explore
a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31
Explore
a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results