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

# 沙盒

> 让用户与你的 API 进行交互

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

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

<Frame>
  <img src="https://mintcdn.com/mintlify-mintlify-add-hello-world-quickstart-48843/jocJo5b89LRoeOR4/images/playground/API-playground-light.png?fit=max&auto=format&n=jocJo5b89LRoeOR4&q=85&s=5ff1379ab70a3f92033c7bf89b492b13" alt="用于触发更新端点的 API 交互测试台。" className="block dark:hidden" width="2534" height="1022" data-path="images/playground/API-playground-light.png" />

  <img src="https://mintcdn.com/mintlify-mintlify-add-hello-world-quickstart-48843/jocJo5b89LRoeOR4/images/playground/API-playground-dark.png?fit=max&auto=format&n=jocJo5b89LRoeOR4&q=85&s=8d3261da2c37f727736e9abceca32d97" 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}
    /your-project
      |- docs.json
      |- openapi.json
    ```
  </Step>

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

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

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

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

    以下示例仅为 `GET /users` 和 `POST /users` 端点生成页面。要生成其他端点的页面，请将相应端点追加到 `pages` 数组中。

    ```json
    "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
{
 "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` 页面。

这两种方式都可以：

* 自定义页面元数据
* 添加示例等额外内容
* 按页面控制 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 规范以生成 WebSocket 参考页面的更多信息，请参阅 [AsyncAPI 设置](/zh/api-playground/asyncapi/setup)。