mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
151a22517f
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
125 lines
2.6 KiB
Plaintext
125 lines
2.6 KiB
Plaintext
---
|
||
title: "AsyncAPI 配置"
|
||
description: "使用 AsyncAPI 规范创建 WebSocket 文档。"
|
||
keywords: ["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}
|
||
/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 本地文件
|
||
"navigation": {
|
||
"tabs": [
|
||
{
|
||
"tab": "API Reference",
|
||
"asyncapi": "/path/to/asyncapi.json"
|
||
}
|
||
]
|
||
}
|
||
|
||
```
|
||
|
||
```json 远程 URL
|
||
"navigation": {
|
||
"tabs": [
|
||
{
|
||
"tab": "API Reference",
|
||
"asyncapi": "https://github.com/asyncapi/spec/blob/master/examples/simple-asyncapi.yml"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
```json 多个文件
|
||
"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
|
||
"navigation": {
|
||
"tabs": [
|
||
{
|
||
"tab": "AsyncAPI",
|
||
"groups": [
|
||
{
|
||
"group": "Websockets",
|
||
"asyncapi": {
|
||
"source": "/path/to/asyncapi.json",
|
||
"directory": "websockets"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
<Note>
|
||
`directory` 字段为可选。若未指定，Mintlify 会将文件添加到文档仓库的 **api-reference** 文件夹中。
|
||
</Note>
|
||
|
||
|
||
<div id="channel-page">
|
||
## 频道页面
|
||
</div>
|
||
|
||
如果你需要更灵活地控制频道的排序，或只想引用特定频道，请创建一个在前言区（frontmatter）中包含 `asyncapi` 属性的 MDX 文件。
|
||
|
||
```mdx
|
||
---
|
||
title: "WebSocket 频道"
|
||
asyncapi: "/path/to/asyncapi.json channelName"
|
||
---
|
||
```
|