# AsyncAPI

SelfDocHub documents event-driven APIs described with [AsyncAPI](https://www.asyncapi.com/). This page explains what is supported and how operations are shown.

## Publishing and support

AsyncAPI versions **2.0–2.6** and **3.x** are accepted as JSON or YAML (root `asyncapi` field). A document is rejected with `400` if it carries `asyncapi` next to another format marker, has no `info`, or declares another major version. Publish it like any other specification (see [Publishing a Specification](/documentation/publishing-specifications)).

- Only **local** references (`#/...`) are followed. A message in an external file or URL is shown as "defined outside this document".
- The document is checked for the structure SelfDocHub relies on, not against the full AsyncAPI JSON Schema.
- There is **no Try-It** for AsyncAPI. Servers are shown on the operation page but never become Try-It environments, and the Environments block is hidden on the service page.

## Operations

The unit of the menu, search, favorites, overlays, Change Log and exports is an **operation**: what the application does with a channel. Version 2.x channels with `publish`/`subscribe` and version 3 `operations` become one model.

The action is shown from the point of view of **your application**:

- `SEND`: the application publishes to the channel.
- `RECV`: the application consumes from the channel.

This inverts the words of 2.x. Its `publish` means clients publish, so the application receives (`RECV`). Its `subscribe` is a `SEND`.

The operation id is the `operationId` (2.x) or the key in `operations` (3.0), otherwise `<action>_<channel address>`. Characters other than letters, digits, `.`, `_` and `-` become `_`. The page address is `/docs/<service>/async/<id>`.

## The operation page

- The header shows the channel address, the action and the protocols of the servers.
- Below are the servers, bindings and security of the operation.
- **Channel & headers** lists channel address parameters (such as `{userId}`) and message headers.
- **Messages** has one tab per message (and per reply message of a 3.0 request/reply operation) with the content type and the payload tree.
- **Example Parameters** shows the address with sample values. **Example Messages** shows the declared examples as `{headers, payload}`; a message without one gets a generated example.

A message written in a schema format other than JSON Schema (Avro, protobuf and so on) has no field tree. Its schema is shown formatted, with the format named above it, and has no field overlays or generated example.

## Overlays

You can overlay the description of an operation, its tags and the service, and the descriptions of fields. Only fields can be overridden, not a message as a whole. Renaming a message or field in the specification orphans its overlay. See [Markdown Overlays](/documentation/markdown-overlays).

## Change Log and breaking changes

Versions are compared operation by operation, also between 2.x and 3.0 versions of one service. Always breaking: a removed operation, a changed action or channel address, an added or removed channel parameter, a removed message, a changed content type and a field whose type changed.

The direction decides the rest. For a `RECV` operation (clients publish) a new required field, a field that became required and a removed enum value break clients. For a `SEND` operation (clients consume) a removed field, a field that stopped being required and an added enum value do. A new optional field, a new message and description changes are not breaking. See [Change Log](/documentation/change-log).

## Search and export

Search covers an operation's title, description, id, channel address, action and tags, but not message names. Exports list the channel and headers as parameters and every message as a response, without a curl command.

## Next steps

- [Versions and Branches](/documentation/versions-and-branches)
- [Export Wizard](/documentation/export-wizard)

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