跳转到主要内容

​
概览

API playground 是一个交互式环境，便于用户测试和探索你的 API 端点。开发者可以构造 API 请求、提交请求，并在不离开文档的情况下查看响应。 参见 触发更新 以查看 API playground 的实际效果。
用于“触发更新”端点的 API playground。
Playground 会基于你的 OpenAPI 规范或 AsyncAPI 模式为端点生成交互式页面。若你修改了 API，Playground 会自动更新相关页面。 我们建议基于 OpenAPI 规范生成 API playground。或者，在你在 docs.json 中定义了基础 URL 和认证方式后，也可以手动创建 API 参考页面。

​
入门

1

添加你的 OpenAPI 规范文件。

使用 Swagger Editor 或 Mint CLI 命令 mint openapi-check <filename> 验证你的 OpenAPI 规范文件。
/your-project
  |- docs.json
  |- openapi.json
2

生成端点页面。

更新你的 docs.json 以引用 OpenAPI 规范。要为 OpenAPI 规范中的所有端点自动生成页面，请在任意导航元素中添加 openapi 属性。此示例会为 openapi.json 中指定的每个端点生成一个页面，并将这些页面归类到 “API reference” 组中。
Generate all endpoint pages
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
若只为特定端点生成页面，请在该导航元素的 pages 属性中列出这些端点。此示例仅为 GET /users 和 POST /users 端点生成页面。若需生成其他端点页面，请将对应端点添加到 pages 数组中。
Generate specific endpoint pages
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
自定义 playground

在 docs.json 中定义以下属性以自定义 API playground。
​
playground
object
API playground 的配置。
​
examples
object
自动生成的 API 示例的配置。

​
配置示例

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

​
基于认证的 playground 显示

使用 auth 显示模式，仅向已通过认证的用户显示交互式 playground。这样可以在公开展示 API 文档的同时，将 playground 的使用限制在已登录用户范围内。 当 display 设置为 auth 时：
  • 已认证用户会看到交互式 playground。
  • 未认证用户不会看到 playground（等同于 none）。
你也可以将 auth 与页面 frontmatter 中的 groups 属性结合使用，仅向特定用户组开放 playground 访问权限。
Page with group-restricted playground
---
title: "创建用户"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---
在本示例中：
  • 页面对所有人公开可见（任何人都可以查看文档）。
  • 只有属于 admin 或 developer groups 的已认证用户才能看到交互式 playground。
  • 不属于这些 groups 的用户不会看到 playground。
如果页面没有 groups 属性，所有已认证用户都会看到交互式 playground。
auth 显示模式要求你已为文档配置好认证。

​
自定义 endpoint 页面

当你需要对 API 文档进行更精细的控制时，可以在 OpenAPI 规范中使用 x-mint 扩展，或者为各个 endpoint 创建单独的 MDX 页面。 这两种方式都可以让你：
  • 自定义页面 metadata
  • 添加示例等额外内容
  • 按页面控制 playground 的行为
推荐使用 x-mint 扩展，这样你的所有 API 文档都可以从 OpenAPI 规范中自动生成，并集中维护在一个文件中。 对于小型 API，或者当你希望在单个页面上逐页试验更改时，推荐使用单独的 MDX 页面。

​
延伸阅读

  • OpenAPI 设置，了解更多关于如何创建 OpenAPI 文档的信息。
  • x-mint 扩展，了解更多关于如何自定义端点页面的信息。
  • MDX 设置，了解更多关于如何手动创建单个 API 参考页面的信息。
  • AsyncAPI 设置，了解更多关于如何创建 AsyncAPI 规范以生成 WebSocket 参考页面的信息。