> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mintlify/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AsyncAPI Setup

> Create WebSocket documentation with AsyncAPI specifications for real-time API endpoints.

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](https://www.asyncapi.com/docs/reference/specification/v3.0.0).

<Tip>
  Use the [AsyncAPI Studio](https://studio.asyncapi.com/) to validate your AsyncAPI schema.
</Tip>

```bash {3} theme={null}
/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

<Tabs>
  <Tab title="Local file">
    ```json theme={null}
    "navigation": {
      "tabs": [
        {
            "tab": "API Reference",
            "asyncapi": "/path/to/asyncapi.json"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Remote URL">
    ```json theme={null}
    "navigation": {
      "tabs": [
        {
            "tab": "API Reference",
            "asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Multiple files">
    ```json theme={null}
    "navigation": {
      "tabs": [
        {
          "tab": "API Reference",
          "asyncapi": [
            "/path/to/events.json",
            "/path/to/webhooks.json"
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Note>
  When you specify multiple AsyncAPI files, each file generates its own set of channel pages.
</Note>

### Examples with groups

For more organization, use groups to structure your AsyncAPI documentation:

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

<Note>
  The `directory` field is optional. If not specified, Mintlify adds the files to the `api-reference` folder of the docs repo.
</Note>

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

```mdx theme={null}
---
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

<Tip>
  The channel name must exactly match the channel identifier in your AsyncAPI specification.
</Tip>