# AsyncAPI 配置 (/zh/api-playground/asyncapi-setup)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 870 · updated: 2026-07-30 -->
Related: [操作台](/zh/api-playground/overview.md), [OpenAPI 设置](/zh/api-playground/openapi-setup.md), [复杂数据类型](/zh/api-playground/complex-data-types.md), [添加 SDK 示例](/zh/api-playground/adding-sdk-examples.md), [管理页面可见性](/zh/api-playground/managing-page-visibility.md), [多种响应](/zh/api-playground/multiple-responses.md)

<div id="demo">
  ## 演示 [#演示]
</div>

参见 [WebSocket 操作台](/zh/api-playground/websocket-playground) 了解 AsyncAPI 操作台的示例。

<div id="add-an-asyncapi-specification-file">
  ## 添加 AsyncAPI 规范文件 [#添加-asyncapi-规范文件]
</div>

要为你的 WebSocket 频道创建页面，你需要提供一个有效的 AsyncAPI 架构文档（JSON 或 YAML 格式），并遵循 [AsyncAPI 3.0 规范](https://www.asyncapi.com/docs/reference/specification/v3.0.0)。

<Tip>
  使用 [AsyncAPI Studio](https://studio.asyncapi.com/) 验证你的 AsyncAPI 架构。
</Tip>

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

<div id="auto-populate-websockets-pages">
  ## 自动生成 WebSocket 页面 [#自动生成-websocket-页面]
</div>

要为 AsyncAPI 模式中的所有通道自动生成页面，请在任意导航元素中添加一个 `asyncapi` 属性。`asyncapi` 属性可以接受文档仓库中 AsyncAPI 模式文档的路径、托管的 AsyncAPI 文档的 URL，或者一个指向 AsyncAPI 模式文档的链接数组。

<div id="examples-with-tabs">
  ### 带选项卡的示例 [#带选项卡的示例]
</div>

<CodeGroup>
  <CodeBlockTabs defaultValue="本地文件" groupId="-+-+-url">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="本地文件">
        本地文件
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="远程 URL">
        远程 URL
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="多个文件">
        多个文件
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

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

      ```
    </CodeBlockTab>

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

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

<Note>
  当你指定多个 AsyncAPI 文件时，每个文件都会生成自己的一组通道页面。
</Note>

<div id="examples-with-groups">
  ### 分组示例 [#分组示例]
</div>

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

<Note>
  `directory` 字段为可选。若未指定，Mintlify 会将文件添加到文档仓库的 **api-reference** 文件夹中。
</Note>

### 嵌套分组示例 [#嵌套分组示例]

`asyncapi` 属性支持嵌套分组。Mintlify 会生成频道页面，并将其与嵌套分组中的现有页面一并添加。

当你希望将 WebSocket 频道作为更大 API 分组下的子分区，或需要将多个 AsyncAPI 规范合并到同一父分组中时，这非常有用。

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

<div id="schema-rendering">
  ## 模式渲染 [#模式渲染]
</div>

数组模式和组合模式（`oneOf`、`anyOf`、`allOf`）会在生成的频道页面中内联展开以显示其子属性。读者可以打开数组项模式的可展开区段，或为每个 `oneOf`/`anyOf` 选项选择一个选项卡，查看所有嵌套字段。

<div id="channel-page">
  ## 频道页面 [#频道页面]
</div>

如果你需要更灵活地控制频道的排序，或只想引用特定频道，请创建一个在前言区（frontmatter）中包含 `asyncapi` 属性的 MDX 文件。

```mdx
---
title: "WebSocket 频道"
asyncapi: "/path/to/asyncapi.json channelName"
---
```