Skip to main content
AsyncAPI is a specification for describing asynchronous APIs, particularly WebSockets. Mintlify supports AsyncAPI 3.0 documents to generate interactive WebSocket documentation.

​
Add an AsyncAPI specification file

To create pages for your websockets, you must have a valid AsyncAPI schema document in either JSON or YAML format that follows the AsyncAPI specification 3.0.
Use the AsyncAPI Studio to validate your AsyncAPI schema.
/your-project
  |- docs.json
  |- asyncapi.json

​
Auto-populate websockets pages

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

​
Examples with tabs

"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "asyncapi": "/path/to/asyncapi.json"
    }
  ]
}
When you specify multiple AsyncAPI files, each file generates its own set of channel pages.

​
Examples with groups

For more organization, use groups to structure your AsyncAPI documentation: 
"navigation": {
  "tabs": [
    {
      "tab": "AsyncAPI",
      "groups": [
        {
          "group": "Websockets",
          "asyncapi": {
            "source": "/path/to/asyncapi.json",
            "directory": "websockets"
          }
        }
      ]
    }
  ]
}
The directory field is optional. If not specified, Mintlify adds the files to the api-reference folder of the docs repo.

​
Channel page

If you want more control over how you order your channels or if you want to reference only specific channels, create an MDX file with the asyncapi property in the frontmatter. 
---
title: "Websocket Channel"
asyncapi: "/path/to/asyncapi.json channelName"
---
This approach allows you to:
  • Customize page metadata and titles
  • Add additional context and documentation around the channel
  • Control which channels appear in your documentation
  • Order channels manually in your navigation
The channel name must exactly match the channel identifier in your AsyncAPI specification.

Build docs developers (and LLMs) love

Get started for freeTalk to us