mintlify__docs/api-playground/asyncapi-setup.mdx

---
title: "AsyncAPI setup"
description: "Set up real-time WebSocket documentation using AsyncAPI specification files to generate interactive channel and message reference pages."
keywords: ["asyncapi", "websocket"]
---

## Demo

See the [WebSocket playground](/api-playground/websocket-playground) for an example of the AsyncAPI playground.

## Add an AsyncAPI specification file

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](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>

```json {3}
/your-project
  |- docs.json
  |- asyncapi.json
```

## Auto-populate WebSocket pages

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.

### Examples with tabs

<CodeGroup>

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

```

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

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

</CodeGroup>

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

### Examples with groups

```json
"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 repository.
</Note>

### Examples with nested groups

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.

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

## Schema rendering

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.

## Channel page

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

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