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

```bash
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.

---
Source: https://selfdochub.com/features/asyncapi-documentation
