Overview

The /speckit.plan command does a great job generating structured, machine-readable specifications for REST and GraphQL APIs:

• REST APIs: Generates OpenAPI specifications (/contracts/openapi.yaml)
• GraphQL APIs: Generates GraphQL schema definitions (/contracts/graphql.schema)

However, event-driven APIs are missing out on this standardization. Currently, async communication patterns (Kafka, WebSocket, message queues, webhooks, etc.) are documented only as markdown files with embedded JSON Schema snippets.

The Problem with Markdown-Only Documentation

When documenting event-driven APIs in markdown:

• Topic/channel names are buried in prose - not formally defined as structured elements
• Publish vs subscribe operations are ambiguous - no clear distinction of message flow direction
• Protocol bindings are unclear - Kafka-specific vs AMQP vs WebSocket details mixed in text
• Inconsistent developer experience - REST gets structured specs, events get markdown

Current State

/speckit.plan with Kafka-based feature

Generated:
├── /contracts/openapi.yaml          ✓ Structured, validated, tooling-rich
└── /contracts/messaging.md          ✗ Prose with JSON Schema snippets

At times, it does not even create this markdown file, it just inlines the details in data-model.

Request: Add AsyncAPI Specification Support

AsyncAPI is the industry-standard specification for event-driven APIs. it is the async equivalent of OpenAPI for REST APIs.

Generate AsyncAPI specifications (/contracts/asyncapi.yaml) for event-driven communication patterns, bringing the same level of structure and standardization to async APIs.

Benefits

1. Standardization - Use industry-standard AsyncAPI spec (Linux Foundation project)
2. Consistency - Event-driven APIs get the same structured treatment as REST and GraphQL
3. Clear definitions - Formal channel/topic structure, explicit publish/subscribe operations
4. Better developer experience - Machine-readable format for both sync and async APIs

Expected Outcome

/speckit.plan with Kafka-based feature

Generated:
├── /contracts/openapi.yaml          ✓ REST API specification
└── /contracts/asyncapi.yaml         ✓ Event-driven API specification
    └── Contains:
        - Formal channel/topic definitions
        - Operations
        - Message schemas (JSON Schema)
        - Protocol bindings (Kafka, WebSocket, etc.)

This brings event-driven APIs to parity with REST and GraphQL, ensuring all API types benefit from structured specifications.

Disclosure

I am an Ambassador at AsyncAPI and contribute by promoting and advancing the adoption of AsyncAPI specification in the developer community.