​
概览

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 规范。在任意导航元素中添加 openapi 属性，即可根据 OpenAPI 文档中定义的每个端点自动生成文档页面。下面的示例会为 openapi.json 中的每个端点生成一个页面，并将它们归类到导航中的 “API reference” 分组下。
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
若只为特定端点生成页面，请在该导航元素的 pages 属性中列出这些端点。此示例仅为 GET /users 和 POST /users 端点生成页面。要生成其他端点的页面，请将相应端点添加到 pages 数组中。
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
自定义 API 操作台

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

​
示例配置

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}
此示例将 API 操作台配置为交互式，并提供 cURL、Python 和 JavaScript 的示例代码片段。代码片段中仅显示必需参数。

​
自定义端点页面

当你需要更细致地控制 API 文档时，可以在 OpenAPI 规范中使用 x-mint 扩展，或为各个端点创建独立的 MDX 页面。 这两种方式都可以：
  • 自定义页面元数据
  • 添加示例等补充内容
  • 按页面控制操作台行为
推荐使用 x-mint 扩展，这样所有 API 文档都能从 OpenAPI 规范自动生成，并统一维护在同一个文件中。 对于体量较小的 API，或当你希望逐页试验更改时，建议使用独立的 MDX 页面。 更多信息请参阅 x-mint 扩展 和 MDX 配置。

​
延伸阅读

  • AsyncAPI 设置，了解如何创建 AsyncAPI 架构以生成 WebSocket 参考页面的更多信息。