跳转到主要内容

​
概览

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"
        ]
      }
  ]
}

​
自定义你的操作台

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

​
延伸阅读

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