AsyncAPI Documentation

Event-driven API documentation for humans and agents.

printing press renders AsyncAPI 3 contracts as first-class API documentation. It does not force an event-driven API into an HTTP request/response shape.

ppress ./events.asyncapi.yaml

The contract type and version are detected from the document. The same static, published, served, JSON and agent-readable outputs used for OpenAPI are available for AsyncAPI.

AsyncAPI 3.x is supported. AsyncAPI 2.x is not supported.

Operations are send and receive

AsyncAPI operations use send and receive actions. Generated pages and navigation render those directions consistently:

← RCV for inbound receive operations
SND → for outbound send operations

The operation summary is used as the page and navigation title when it exists. operationId provides the stable page slug and fallback label.

An operation page brings together:

the action and channel address
the operation ID and description
channel parameters and protocol bindings
security requirements
one or more messages
reply channels and reply messages
external documentation and extensions

Channels and protocols

The channel occupies the same structural position that a method and path occupy in OpenAPI documentation. It shows the channel component, address, parameters and bindings without duplicating the address elsewhere on the page.

Common protocols and providers are rendered as first-class protocol labels, including Kafka, AMQP, MQTT, NATS, Pulsar, Redis, SNS, SQS, Solace, IBM MQ, JMS, STOMP, WebSocket, HTTP, Mercure, Anypoint MQ and Google Pub/Sub.

Protocol bindings remain attached to the server, operation, channel or message that owns them.

Messages and content

Messages are rendered like the payload-bearing side of an operation, not as an unexplained generic object.

Each message can show:

name, title, summary and description
content type
payload and header schemas
traits and correlation IDs
multiple named examples, including example headers and payloads
bindings, extensions and external documentation

Referenced messages get their own model pages. Inline messages and schemas stay inside the operation that owns them.

JSON Schema-compatible payloads use the same property, mock example, reference, composition and class-diagram renderers as OpenAPI schemas. A declared non-JSON schema format, such as Avro, is preserved and rendered as raw schema content. It is never parsed as if it were JSON Schema.

AsyncAPI model pages

The model navigation is generated from the components that exist in the contract. It can include:

schemas
messages
channels
parameters
security schemes
replies and reply addresses
correlation IDs
operation traits and message traits

Cross references connect these pages back to the operations and components that consume or reference them. Schema model pages also include generated examples, property rendering, class diagrams and the dependency explorer when the source contains enough relationship data.

Replies

AsyncAPI replies are kept with the send or receive operation that owns them. The generated reply section resolves:

the reply component
reply address
reply channel
reply messages

Referenced reply objects and reply addresses also receive model pages, so operation pages can stay focused while deeper contract details remain linkable.

Source browsing

Use --include-spec to copy the source contract into the generated documentation and turn Defined in locations into links:

ppress --include-spec ./events.asyncapi.yaml

For multi-file contracts, contained local reference files are copied under api-docs/spec/ and links point to the actual source file and line.

Mixed API catalogs

Catalog mode can discover OpenAPI and AsyncAPI 3 contracts from the same directory tree:

ppress ./services

Each catalog entry records its contract kind and renders with the correct operation and model semantics. See API Catalog for discovery, grouping and incremental build behavior.