Describe every channel in an AsyncAPI document

How to do it

An event without a written contract is a promise nobody can check. AsyncAPI 3.1 describes channels, the send and receive operations on them, and each message's payload schema, in YAML or JSON. Write payloads as JSON Schema, Avro or Protobuf, and reuse them from components. Generate docs and test fixtures from the document, and validate it in CI. Webhooks that a public API sends can live in OpenAPI's webhooks section instead, as Version event payloads says. Each consumer tests against the document as Check the contract between services describes.

Examples

YAML example

asyncapi: 3.1.0
info:
  title: Example Shop orders
  version: 2.4.0
channels:
  orderShipped:
    address: shop.orders.shipped
    messages:
      orderShipped:
        $ref: '#/components/messages/orderShipped'
operations:
  sendOrderShipped:
    action: send
    channel:
      $ref: '#/channels/orderShipped'
components:
  messages:
    orderShipped:
      payload:
        type: object
        required: [orderId, shippedAt]
        properties:
          orderId: { type: string }
          shippedAt: { type: string, format: date-time }

JavaScript example

import { Parser } from '@asyncapi/parser';
import { readFile } from 'node:fs/promises';

const { diagnostics } = await new Parser().parse(await readFile('asyncapi.yaml', 'utf8'));
const errors = diagnostics.filter(d => d.severity === 0);
if (errors.length) throw new Error(errors.map(d => d.message).join('\n'));

Python example

import subprocess

def validate_asyncapi(path: str) -> None:
    subprocess.run(["asyncapi", "validate", path], check=True)

How to check

CI validates each AsyncAPI document and fails on any error. A script lists the topics or queues each service uses in code, and every one appears as a channel in that service's document.

Sources

• AsyncAPI Specification 3.1.0

Related rules

• EVT-3 Version event payloads in Integration and events
• TST-14 Check the contract between services in Testing
• EVT-4 Let a schema registry refuse breaking changes in Integration and events