AsyncAPI

SelfDocHub documents event-driven APIs described with AsyncAPI. 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).

  • 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.

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.

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#

Last updated: