AsyncAPI setup

Set up real-time WebSocket documentation using AsyncAPI specification files to generate interactive channel and message reference pages.

See the WebSocket playground for an example of the AsyncAPI playground.

To create pages for your WebSocket channels, you must have a valid AsyncAPI schema document in JSON or YAML format. The document must follow the AsyncAPI specification 3.0.

/your-project  |- docs.json  |- asyncapi.json

To automatically generate pages for all channels in your AsyncAPI schema, add an asyncapi property to any navigation element. The property accepts a path to an AsyncAPI schema document in your documentation repo or a URL to a hosted AsyncAPI document. It also accepts an array of links to AsyncAPI schema documents.

"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "asyncapi": "/path/to/asyncapi.json"
    }
  ]
}

"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
    }
  ]
}

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "asyncapi": [
        "/path/to/events.json",
        "/path/to/webhooks.json"
      ]
    }
  ]
}

"navigation": {
  "tabs": [
    {
      "tab": "AsyncAPI",
      "groups": [
        {
          "group": "Websockets",
          "asyncapi": {
            "source": "/path/to/asyncapi.json",
            "directory": "websockets"
          }
        }
      ]
    }
  ]
}

The asyncapi property supports nested groups. Mintlify generates the channel pages and adds them to the nested group, alongside any existing pages.

Use nested groups to organize WebSocket channels as a subsection of a broader API group. You can also combine multiple AsyncAPI specifications under a shared parent group.

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Voice API",
          "pages": [
            "voice/overview",
            {
              "group": "Voice API Commands",
              "asyncapi": "/path/to/voice-asyncapi.json"
            }
          ]
        }
      ]
    }
  ]
}

Array schemas and combinatorial schemas (oneOf, anyOf, allOf) expand to show their child attributes inline in the generated channel pages. Readers can open the expandable section for an array item schema. They can also select a tab for each oneOf/anyOf option to see all nested fields.

To control channel order or reference only specific channels, create an MDX file with the asyncapi property in the frontmatter.

---
title: "Websocket Channel"
asyncapi: "/path/to/asyncapi.json channelName"
---

• API playground overview
• Migrate from another platform
• Migrate from Docusaurus