跳转到主要内容

​
概览

API 操作台是一个交互式环境，便于用户测试并探索你的 API 端点。开发者可以构造 API 请求、提交请求，并在不离开文档的情况下查看响应。
用于触发更新端点的 API 操作台。
操作台会基于你的 OpenAPI 规范或 AsyncAPI 架构自动生成，因此对 API 的任何更新都会自动反映在操作台中。你也可以在 docs.json 中定义基础 URL 和认证方式后，手动创建 API 参考页面。 我们建议基于 OpenAPI 规范生成你的 API 操作台。参见 OpenAPI 设置 了解创建 OpenAPI 文档的更多信息。

​
入门

1

添加你的 OpenAPI 规范文件。

使用 Swagger Editor 或 Mint CLI 确认你的 OpenAPI 规范文件有效。
/your-project
  |- docs.json
  |- openapi.json
2

配置 `docs.json`。

更新你的 docs.json 以引用 OpenAPI 规范。在任一 navigation 元素中添加 openapi 属性，可根据 OpenAPI 文档中定义的每个端点自动生成对应页面，填充文档。下例会为 openapi.json 中的每个端点生成一个页面，并将它们归入导航中的“API reference”分组。
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
如只需为特定端点生成页面，请在该 navigation 元素的 pages 属性中列出这些端点。下例仅为 GET /users 和 POST /users 端点生成页面。若要生成其他端点页面，请将相应端点追加到 pages 数组中。
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
自定义操作台

你可以在 docs.json 中通过定义以下属性来自定义 API 操作台。
​
playground
object
API 操作台的相关配置。
​
examples
object
自动生成的 API 示例配置。

​
配置示例

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required",
     "prefill": true
   }
 }
}
此示例将 API 操作台配置为可交互，并提供 cURL、Python 和 JavaScript 的示例代码片段。代码片段仅显示必填参数，且操作台会用示例值预填请求正文。

​
自定义端点页面

当你需要对 API 文档有更精细的控制时，可以在 OpenAPI 规范中使用 x-mint 扩展，或为端点创建独立的 MDX 页面。 这两种方式都支持你：
  • 自定义页面 metadata
  • 添加示例等额外内容
  • 按页面控制 playground 的行为
推荐使用 x-mint 扩展，这样你的全部 API 文档都能基于 OpenAPI 规范自动生成，并集中维护在同一个文件中。 对于小型 API，或当你想按页面试验改动时，建议使用独立的 MDX 页面。 更多信息，请参阅 x-mint 扩展 和 MDX 设置。

​
延伸阅读

  • AsyncAPI Setup：了解如何创建 AsyncAPI 架构，以生成 WebSocket 参考页面。