> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# AsyncAPI 配置

> 使用 AsyncAPI 规范创建 WebSocket 文档。

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

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

<div id="add-an-asyncapi-specification-file">
  ## 添加 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} theme={null}
/your-project
  |- docs.json
  |- asyncapi.json
```

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

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

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

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

  ```

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

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

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

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

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

<Note>
  `directory` 字段为可选。若未指定，文件将放置在文档仓库的 **api-reference** 文件夹中。
</Note>

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

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

```mdx theme={null}
---
title: "WebSocket 频道"
asyncapi: "/path/to/asyncapi.json channelName"
---
```