AsyncAPI 配置 - Mintlify

演示

参见 WebSocket 操作台了解 AsyncAPI 操作台的示例。

添加 AsyncAPI 规范文件

要为你的 WebSocket 频道创建页面，你需要提供一个有效的 AsyncAPI 架构文档（JSON 或 YAML 格式），并遵循 AsyncAPI 3.0 规范。

使用 AsyncAPI Studio 验证你的 AsyncAPI 架构。

/your-project
  |- docs.json
  |- asyncapi.json

自动生成 WebSocket 页面

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

带选项卡的示例

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

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

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

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

分组示例

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

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

嵌套分组示例

asyncapi 属性支持嵌套分组。Mintlify 会生成频道页面，并将其与嵌套分组中的现有页面一并添加。当你希望将 WebSocket 频道作为更大 API 分组下的子分区，或需要将多个 AsyncAPI 规范合并到同一父分组中时，这非常有用。

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

模式渲染

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

频道页面

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

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

​演示

​添加 AsyncAPI 规范文件

​自动生成 WebSocket 页面

​带选项卡的示例

​分组示例

​嵌套分组示例

​模式渲染

​频道页面

演示

添加 AsyncAPI 规范文件

自动生成 WebSocket 页面

带选项卡的示例

分组示例

嵌套分组示例

模式渲染

频道页面