AsyncAPI setup

Use AsyncAPI when your product exposes channels, messages, or event streams that do not fit a REST-first OpenAPI reference.

​

Add a schema file

Store the AsyncAPI document alongside the rest of your docs assets.

docsalot-docs/
  layout.json
  asyncapi/
    realtime.yaml

Validate the file before wiring it into navigation. AsyncAPI Studio is a good quick validator for this.

​

Configure the schema

Register the schema in layout.json.

{
  "api": {
    "asyncapi": "asyncapi/realtime.yaml"
  }
}

​

Add it to navigation

For a dedicated realtime section, attach the schema to a navigation group.

{
  "group": "Realtime APIs",
  "asyncapi": "asyncapi/realtime.yaml"
}

This is useful for:

• WebSocket channels
• webhook payload catalogs
• streaming event contracts
• publish/subscribe systems

​

When to use AsyncAPI vs OpenAPI

• Use OpenAPI for request-response HTTP endpoints.
• Use AsyncAPI for channels, messages, and event schemas.
• Use both when your product has a REST API and realtime events.

If your API is mostly REST with a few custom tutorial pages, Create manual API pages is often still the simplest supplement.