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

# Playground

> 让用户与你的 API 交互

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

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

<Frame>
  <img src="https://mintcdn.com/omer-914cc1c6/zyJsbuZtXQKHf9Ui/images/playground/API-playground-light.png?fit=max&auto=format&n=zyJsbuZtXQKHf9Ui&q=85&s=cbd122bacf76749c62b9515b60d55dcd" alt="用于触发更新端点的 API 操作台。" className="block dark:hidden" width="2534" height="1022" data-path="images/playground/API-playground-light.png" />

  <img src="https://mintcdn.com/omer-914cc1c6/zyJsbuZtXQKHf9Ui/images/playground/API-playground-dark.png?fit=max&auto=format&n=zyJsbuZtXQKHf9Ui&q=85&s=b119dc4c0ce2427d76589461085e3a5d" alt="用于触发更新端点的 API 操作台。" className="hidden dark:block" width="2534" height="1022" data-path="images/playground/API-playground-dark.png" />
</Frame>

操作台会基于你的 OpenAPI 规范或 AsyncAPI 架构自动生成，因此对 API 的任何更新都会自动反映在操作台中。你也可以在 `docs.json` 中定义基础 URL 和认证方式后，手动创建 API 参考页面。

我们建议基于 OpenAPI 规范生成你的 API 操作台。参见 [OpenAPI 设置](/zh/api-playground/openapi-setup) 了解创建 OpenAPI 文档的更多信息。

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

<Steps>
  <Step title="添加你的 OpenAPI 规范文件。">
    <Info>
      使用 [Swagger Editor](https://editor.swagger.io/) 或 [Mint CLI](https://www.npmjs.com/package/mint) 确认你的 OpenAPI 规范文件有效。
    </Info>

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

  <Step title="配置 `docs.json`。">
    更新 `docs.json` 以引用你的 OpenAPI 规范。在任意导航元素中添加 `openapi` 属性，可根据 OpenAPI 文档中定义的每个端点自动生成相应的文档页面。

    下例会为 `openapi.json` 中的每个端点生成一个页面，并将它们归类到导航中的 “API reference” 组下。

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

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

    下例仅为 `GET /users` 和 `POST /users` 端点生成页面。若要生成其他端点页面，请将更多端点添加到 `pages` 数组中。

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

<div id="customizing-your-playground">
  ## 自定义你的操作台
</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;">
      API 操作台的显示模式。

      * `"interactive"`：显示交互式操作台。
      * `"simple"`：仅显示可复制的端点，不包含操作台。
      * `"none"`：不显示任何内容。

      默认为 `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>
  </Expandable>
</ResponseField>

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

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

此示例将 API 操作台配置为可交互，并提供 cURL、Python 和 JavaScript 的示例代码片段。代码片段中仅展示必填参数。

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

当你需要对 API 文档有更精细的控制时，可以在 OpenAPI 规范中使用 `x-mint` 扩展，或为端点创建独立的 `MDX` 页面。

这两种方式都支持你：

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

推荐使用 `x-mint` 扩展，这样你的全部 API 文档都能基于 OpenAPI 规范自动生成，并集中维护在同一个文件中。

对于小型 API，或当你想按页面试验改动时，建议使用独立的 `MDX` 页面。

更多信息，请参阅 [x-mint 扩展](/zh/api-playground/openapi-setup#x-mint-extension) 和 [MDX 设置](/zh/api-playground/mdx/configuration)。

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

* [AsyncAPI Setup](/zh/api-playground/asyncapi/setup)：了解如何创建 AsyncAPI 架构，以生成 WebSocket 参考页面。