跳转到主要内容

​
概览

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

​
延伸阅读

  • 如需了解如何创建 AsyncAPI 规范以生成 WebSocket 参考页面的更多信息，请参阅 AsyncAPI 设置。