# AsyncAPI setup (/api-playground/asyncapi-setup)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1102 · updated: 2026-07-30 -->
Related: [API playground overview](/api-playground/overview.md), [OpenAPI setup](/api-playground/openapi-setup.md), [Complex data types](/api-playground/complex-data-types.md), [Add SDK examples](/api-playground/adding-sdk-examples.md), [Manage page visibility](/api-playground/managing-page-visibility.md), [Multiple responses](/api-playground/multiple-responses.md)

## Demo [#demo]

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

## Add an AsyncAPI specification file [#add-an-asyncapi-specification-file]

To create pages for your WebSocket channels, 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>

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

## Auto-populate WebSocket pages [#auto-populate-websocket-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, or an array of links to AsyncAPI schema documents.

### Examples with tabs [#examples-with-tabs]

<CodeGroup>
  <CodeBlockTabs defaultValue="Local file" groupId="local-file+multiple-files+remote-url">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Local file">
        Local file
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Remote URL">
        Remote URL
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Multiple files">
        Multiple files
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

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

      ```
    </CodeBlockTab>

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

    <CodeBlockTab value="Multiple files">
      ```json  
      "navigation": {
        "tabs": [
          {
            "tab": "API Reference",
            "asyncapi": [
              "/path/to/events.json",
              "/path/to/webhooks.json"
            ]
          }
        ]
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

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

### Examples with groups [#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 [#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.

This is useful when you want to organize WebSocket channels as a subsection of a broader API group, or when you need to 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 [#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 or select a tab for each `oneOf`/`anyOf` option to see all nested fields.

## Channel page [#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
---
title: "Websocket Channel"
asyncapi: "/path/to/asyncapi.json channelName"
---
```