Messages travelling through channels between services

AsyncAPI documentation tool for event-driven APIs

Event-driven systems have APIs too: topics, queues, message formats. They are often described in AsyncAPI files that nobody opens because there is no good place to read them. SelfDocHub renders AsyncAPI next to your REST and GraphQL services, so a developer looks in one place whether they are calling an endpoint or subscribing to a topic.

What is supported#

AsyncAPI 2.0 to 2.6 and 3.x are accepted as JSON or YAML. Publish a file the same way as any other specification, with one HTTP call from CI:

curl -X POST https://docs.example.com/api/v1/services/orders-events/spec \
  -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
  --data-binary @asyncapi.yaml

The format is detected from the asyncapi field in the document. Version 2.x channels with publish and subscribe, and version 3 operations, become one common model, so the portal looks the same for both.

Operations from the point of view of your application#

The unit of the menu, search, favorites, overlays, change log and exports is an operation: what the application does with a channel. It is shown as SEND when the application publishes to the channel and RECV when it consumes from it.

The operation page shows the channel address, the action and the protocols of its servers, then the servers, bindings and security, channel parameters and message headers, and one tab per message with the content type and the payload as a field tree. Example parameters and example messages are shown too, and a message without a declared example gets a generated one. Messages written in another schema format, such as Avro or protobuf, are shown formatted, with the format named above them.

Versions and breaking changes#

Every publish is a version with its own change log. AsyncAPI uses direction-aware rules to decide what is breaking. A removed operation, a changed channel address or a changed field type always break clients. Beyond that, for an operation that receives messages a new required field breaks the publishers, while for an operation that sends messages a removed field breaks the consumers. A new optional field or a new message does not. Notifications can be limited to breaking changes only, so the team that consumes a topic hears about it before the deploy, not after.

Alongside everything else#

AsyncAPI services share the portal with OpenAPI, GraphQL and OpenRPC ones: one search, one set of teams and roles, one export, one MCP server for AI assistants. Markdown overlays let you add the context a generated page cannot, such as who owns a topic and what the retry policy is.

Limits worth knowing#

SelfDocHub checks the structure it relies on rather than validating against the full AsyncAPI JSON Schema, and external references are not followed. There is no Try-It for AsyncAPI.

Frequently asked questions

Which AsyncAPI versions are supported?

Versions 2.0 to 2.6 and 3.x, as JSON or YAML. Only local references are followed; a message defined in an external file is shown as defined outside the document.

Is there Try-It for AsyncAPI?

No. Servers are shown on the operation page but never become Try-It environments.

How are operations named?

The unit is an operation, shown from the point of view of your application: SEND when it publishes to a channel and RECV when it consumes from one, so the words are the opposite of the 2.x publish and subscribe.

Run it on your own infrastructure

The Free plan includes a license for one installation. Start with Docker in a few minutes, no credit card needed.