> ## Documentation Index
> Fetch the complete documentation index at: https://smartac-mintlify-d7bc03a0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 操作台

> 让开发者在文档中直接测试 API 端点，交互式演练场可发送真实请求并显示响应结果。

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

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

<Frame>
  <img src="https://mintcdn.com/smartac-mintlify-d7bc03a0/I8_JJvG8KzC_6raX/images/playground/API-playground-light.png?fit=max&auto=format&n=I8_JJvG8KzC_6raX&q=85&s=c0776725aef86e1bfca627217662803e" alt="用于“触发更新”端点的 API playground。" className="block dark:hidden" width="2534" height="1022" data-path="images/playground/API-playground-light.png" />

  <img src="https://mintcdn.com/smartac-mintlify-d7bc03a0/I8_JJvG8KzC_6raX/images/playground/API-playground-dark.png?fit=max&auto=format&n=I8_JJvG8KzC_6raX&q=85&s=81d33fbb4ba9120d15bf128928da279a" alt="用于“触发更新”端点的 API playground。" className="hidden dark:block" width="2534" height="1022" data-path="images/playground/API-playground-dark.png" />
</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 validate` 验证你的 OpenAPI 规范文件。
    </Tip>

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

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

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

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

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

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

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

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

<div id="customize-your-playground">
  ## 自定义您的 API 操作台
</div>

在 `docs.json` 中定义以下属性，以自定义您的 API 操作台。

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

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

      * `"interactive"`：显示交互式 API 操作台。
      * `"simple"`：显示可复制的端点，不显示 API 操作台。
      * `"none"`：不显示任何内容。
      * `"auth"`：仅向已认证用户显示交互式 API 操作台。未认证用户或不在所需组中的用户将看不到 API 操作台。

      默认为 `interactive`。
    </ResponseField>

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

      当设置为 `true` 时，playground 请求会通过 Mintlify 的服务器路由。当设置为 `false` 时，playground 会直接从浏览器向你的 API 发送请求。当你的 API 接受浏览器直接请求且不需要 Mintlify 代理流量时，请设置为 `false`。例如，当你的 API 需要无法通过代理转发的特定请求头时，或者当你需要请求直接从用户浏览器发起以进行身份验证时。
    </ResponseField>

    <ResponseField name="credentials" type="boolean">
      当 `proxy` 为 `false` 时，是否在跨域请求中包含 cookies、授权头和 TLS 客户端证书。默认为 `false`。

      当为 `true` 且 `proxy` 为 `false` 时，playground 会在发送请求时附带浏览器管理的凭据。例如，当你的 API 使用基于 cookie 的身份验证或 HTTP 会话令牌时。

      当 `proxy` 为 `true` 时，此选项无效。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="url" type="&#x22;full&#x22;">
  端点标头中 base URL 的显示模式。设置为 `full` 时，每个端点页面都会显示完整的 base URL。默认情况下，仅显示相对端点路径。
</ResponseField>

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

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

      语言按指定顺序显示。

      <Accordion title="所有支持的语言">
        | 显示名称       | Key          | 别名                        |
        | ---------- | ------------ | ------------------------- |
        | cURL       | `bash`       | `curl`, `sh`, `shell`     |
        | Python     | `python`     | `py`                      |
        | JavaScript | `javascript` | `js`                      |
        | Node.js    | `node`       | `nodejs`, `node.js`       |
        | PHP        | `php`        |                           |
        | Go         | `go`         | `golang`                  |
        | Java       | `java`       |                           |
        | Ruby       | `ruby`       | `rb`                      |
        | PowerShell | `powershell` |                           |
        | Swift      | `swift`      |                           |
        | C#         | `csharp`     | `c#`                      |
        | .NET       | `dotnet`     | `.net`, `.NET`, `dot-net` |
        | TypeScript | `typescript` | `ts`                      |
        | C          | `c`          |                           |
        | C++        | `c++`        | `cpp`                     |
        | Kotlin     | `kotlin`     | `kt`                      |
        | Rust       | `rust`       | `rs`                      |
        | Dart       | `dart`       | `flutter`                 |
      </Accordion>
    </ResponseField>

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

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

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

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

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

```json theme={null}
{
 "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 theme={null}
---
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="response-rendering">
  ## 响应渲染
</div>

Playground 会根据 API 返回的 `Content-Type` 响应头自动渲染响应。

* **图片**：内联渲染 (`image/*`)。
* **音频**：使用内置音频播放器渲染 (`audio/*`)。
* **视频**：使用内置视频播放器渲染 (`video/*`)。任何 `video/*` 类型的响应，如 `video/mp4` 或 `video/webm`，都会在 playground 中直接显示为可播放的视频。
* **所有其他响应**：在代码块中显示。

<div id="parameter-anchor-links">
  ## 参数锚点链接
</div>

API playground 中的每个参数都有一个可点击的锚点链接。将鼠标悬停在参数名称上以显示链接图标，然后点击即可复制该参数的直接链接。

使用参数锚点链接可以：

* 在技术支持对话或文档中分享指向特定参数的链接
* 从其他页面或外部资源直接跳转到某个参数
* 将常用参数添加到书签

URL 格式为 `你的文档网址/端点路径#参数名称`。对于嵌套参数，锚点会包含父级路径。

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

* [OpenAPI 设置](/zh/api-playground/openapi-setup)，详细了解如何创建 OpenAPI 文档。
* [x-mint 扩展](/zh/api-playground/openapi-setup#customize-your-endpoint-pages)，详细了解如何自定义端点页面。
* [MDX 设置](/zh/api-playground/mdx-setup)，详细了解如何手动创建单个 API 参考页面。
* [AsyncAPI 设置](/zh/api-playground/asyncapi-setup)，详细了解如何创建 AsyncAPI 模式以生成 WebSocket 参考页面。