mintlify__docs/zh/api-playground/overview.mdx

---
title: "Playground"
description: "让开发者可直接在文档中测试 API 端点。"
keywords: ["交互式", "API", "端点测试", "实时 API 请求", "请求构建器"]
---

<div id="overview">
  ## 概览
</div>

API playground 是一个交互式环境，便于用户测试和探索你的 API 端点。开发者可以构造 API 请求、提交请求，并在不离开文档的情况下查看响应。

参见 [触发更新](/zh/api/update/trigger) 以查看 API playground 的实际效果。

<Frame>
  <img src="/images/playground/API-playground-light.png" alt="用于“触发更新”端点的 API playground。" className="block dark:hidden" />

  <img src="/images/playground/API-playground-dark.png" alt="用于“触发更新”端点的 API playground。" className="hidden dark:block" />
</Frame>

Playground 会基于你的 OpenAPI 规范或 AsyncAPI 模式为端点生成交互式页面。若你修改了 API，Playground 会自动更新相关页面。

我们建议基于 OpenAPI 规范生成 API playground。或者，在你在 `docs.json` 中定义了基础 URL 和认证方式后，也可以手动创建 API 参考页面。

<div id="get-started">
  ## 入门
</div>

<Steps>
  <Step title="添加你的 OpenAPI 规范文件。">
    <Tip>
      使用 [Swagger Editor](https://editor.swagger.io/) 或 [Mint CLI](https://www.npmjs.com/package/mint) 命令 `mint openapi-check <filename>` 验证你的 OpenAPI 规范文件。
    </Tip>

    ```bash {3}
    /your-project
      |- docs.json
      |- openapi.json
    ```
  </Step>

  <Step title="生成端点页面。">
    更新你的 `docs.json` 以引用 OpenAPI 规范。

    **要为 OpenAPI 规范中的所有端点自动生成页面**，请在任意导航元素中添加 `openapi` 属性。

    此示例会为 `openapi.json` 中指定的每个端点生成一个页面，并将这些页面归类到 “API reference” 组中。

    ```json Generate all endpoint pages
    "navigation": {
      "groups": [
        {
          "group": "API reference",
          "openapi": "openapi.json"
        }
      ]
    }
    ```

    **若只为特定端点生成页面**，请在该导航元素的 `pages` 属性中列出这些端点。

    此示例仅为 `GET /users` 和 `POST /users` 端点生成页面。若需生成其他端点页面，请将对应端点添加到 `pages` 数组中。

    ```json Generate specific endpoint pages
    "navigation": {
      "groups": [
          {
            "group": "API reference",
            "openapi": "openapi.json",
            "pages": [
              "GET /users",
              "POST /users"
            ]
          }
      ]
    }
    ```
  </Step>
</Steps>

<div id="customize-your-playground">
  ## 自定义 playground
</div>

在 `docs.json` 中定义以下属性以自定义 API playground。

<ResponseField name="playground" type="object">
  API playground 的配置。

  <Expandable title="playground" defaultOpen="True">
    <ResponseField name="display" type="&#x22;interactive&#x22; | &#x22;simple&#x22; | &#x22;none&#x22; | &#x22;auth&#x22;">
      API playground 的显示模式。

      * `"interactive"`：显示交互式 playground。
      * `"simple"`：显示可复制的端点，不包含 playground。
      * `"none"`：不显示任何内容。
      * `"auth"`：仅向已通过身份验证的用户显示交互式 playground。未通过身份验证的用户或不在必需 groups 中的用户将看不到 playground。

      默认为 `interactive`。
    </ResponseField>

    <ResponseField name="proxy" type="boolean" defaultOpen="True">
      是否通过代理服务器转发 API 请求。默认为 `true`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="examples" type="object">
  自动生成的 API 示例的配置。

  <Expandable title="examples" defaultOpen="True">
    <ResponseField name="languages" type="array of string">
      自动生成的 API 代码片段所使用的示例语言。

      语言按指定顺序显示。
    </ResponseField>

    <ResponseField name="defaults" type="&#x22;required&#x22; | &#x22;all&#x22;">
      是否在 API 示例中显示可选参数。默认为 `all`。
    </ResponseField>

    <ResponseField name="prefill" type="boolean">
      是否使用来自 schema 示例的数据预填充 API playground。启用后，playground 会根据 OpenAPI 规范中的示例值自动填充请求字段。默认为 `false`。
    </ResponseField>

    <ResponseField name="autogenerate" type="boolean">
      是否根据 API 规范为端点生成代码示例。默认为 `true`。当设置为 `false` 时，只有手动编写的代码示例（来自 OpenAPI 规范中的 `x-codeSamples` 或 MDX 中的 `<RequestExample>` 组件）会显示在 API playground 中。
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="example-configuration">
  ### 配置示例
</div>

此示例将 API playground 配置为可交互，并提供 cURL、Python 和 JavaScript 的示例代码片段。代码片段仅显示必填参数，且 playground 会为请求体预填示例值。

```json
{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required",
     "prefill": true
   }
 }
}
```

<div id="auth-based-playground-display">
  ### 基于认证的 playground 显示
</div>

使用 `auth` 显示模式，仅向已通过认证的用户显示交互式 playground。这样可以在公开展示 API 文档的同时，将 playground 的使用限制在已登录用户范围内。

当 `display` 设置为 `auth` 时：

* 已认证用户会看到交互式 playground。
* 未认证用户不会看到 playground（等同于 `none`）。

你也可以将 `auth` 与页面 frontmatter 中的 `groups` 属性结合使用，仅向特定用户组开放 playground 访问权限。

```mdx Page with group-restricted playground
---
title: "创建用户"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---
```

在本示例中：

* 页面对所有人公开可见（任何人都可以查看文档）。
* 只有属于 `admin` 或 `developer` groups 的已认证用户才能看到交互式 playground。
* 不属于这些 groups 的用户不会看到 playground。

如果页面没有 `groups` 属性，所有已认证用户都会看到交互式 playground。

<Note>
  `auth` 显示模式要求你已为文档配置好[认证](/zh/deploy/authentication-setup)。
</Note>

<div id="custom-endpoint-pages">
  ### 自定义 endpoint 页面
</div>

当你需要对 API 文档进行更精细的控制时，可以在 OpenAPI 规范中使用 `x-mint` 扩展，或者为各个 endpoint 创建单独的 MDX 页面。

这两种方式都可以让你：

* 自定义页面 metadata
* 添加示例等额外内容
* 按页面控制 playground 的行为

推荐使用 `x-mint` 扩展，这样你的所有 API 文档都可以从 OpenAPI 规范中自动生成，并集中维护在一个文件中。

对于小型 API，或者当你希望在单个页面上逐页试验更改时，推荐使用单独的 MDX 页面。

<div id="further-reading">
  ## 延伸阅读
</div>

* [OpenAPI 设置](/zh/api-playground/openapi-setup)，了解更多关于如何创建 OpenAPI 文档的信息。
* [x-mint 扩展](/zh/api-playground/openapi-setup#x-mint-extension)，了解更多关于如何自定义端点页面的信息。
* [MDX 设置](/zh/api-playground/mdx-setup)，了解更多关于如何手动创建单个 API 参考页面的信息。
* [AsyncAPI 设置](/zh/api-playground/asyncapi-setup)，了解更多关于如何创建 AsyncAPI 规范以生成 WebSocket 参考页面的信息。