# 故障排查 (/zh/api-playground/troubleshooting)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 960 · updated: 2026-07-30 -->
Related: [操作台](/zh/api-playground/overview.md), [OpenAPI 设置](/zh/api-playground/openapi-setup.md), [复杂数据类型](/zh/api-playground/complex-data-types.md), [添加 SDK 示例](/zh/api-playground/adding-sdk-examples.md), [管理页面可见性](/zh/api-playground/managing-page-visibility.md), [多种响应](/zh/api-playground/multiple-responses.md)

如果你的 API 页面显示不正确，请先检查以下常见配置问题。

<AccordionGroup>
  <Accordion title="我的所有 OpenAPI 页面都是空白的">
    在这种情况下，很可能是 Mintlify 找不到你的 OpenAPI 文档，或者你的 OpenAPI 文档无效。

    在本地运行 `mint dev` 通常能暴露出其中一些问题。

    要验证你的 OpenAPI 文档是否通过校验：

    1. 访问[此校验器](https://editor.swagger.io/)。
    2. 切换到 **Validate text** 标签页。
    3. 粘贴你的 OpenAPI 文档。
    4. 点击 &#x2A;*Validate it!**

    如果下方出现的文本框带有绿色边框，说明你的文档已通过校验。
    这是 Mintlify 用于校验 OpenAPI 文档的同一套校验包，因此如果你的文档在这里通过校验，很大概率问题出在其他地方。

    此外，Mintlify 不支持 OpenAPI 2.0。如果你的文档使用该版本规范，可能会遇到此问题。你可以在 [editor.swagger.io](https://editor.swagger.io/) 上转换文档 (Edit > Convert to OpenAPI 3) ：

    <Frame>
      ![展开 Edit 菜单并高亮“Convert to OpenAPI 3”菜单项的 Swagger Editor 截图。](/_assets/0cd011b0433fb2954fc6a21a726ad9a709d8141285e20f99a31c02df16dac172)
    </Frame>
  </Accordion>

  <Accordion title="我的某个 OpenAPI 页面是完全空白的">
    这通常是由于页面 metadata 中的 `openapi` 字段拼写错误导致的。请确保
    HTTP 方法和路径与 OpenAPI 文档中的 HTTP 方法和路径一致。

    <Note>
      Mintlify 会自动解析 `openapi` 引用与 OpenAPI 规范之间尾部斜杠的差异。
      例如，`GET /users/{id}/` 可以匹配规范中的路径 `/users/{id}`。
    </Note>

    下面是一个可能出错的示例：

    ```mdx title="get-user.mdx"
    ---
    openapi: "GET /user/{id}"
    ---
    ```

    ```yaml title="openapi.yaml"
    paths:
      "/users/{id}":
        get: ...
    ```

    请注意，`openapi` 字段中的路径是 `/user/{id}` (单数)，而 OpenAPI 文档中的路径是 `/users/{id}` (复数)。

    另一个常见问题是文件名拼写错误。如果你在 `openapi` 字段中指定了某个特定的 OpenAPI 文档，请确保文件名正确。例如，如果你有两个 OpenAPI 文档 `openapi/v1.json` 和 `openapi/v2.json`，你的 metadata 可能如下所示：

    ```mdx title="api-reference/v1/users/get-user.mdx"
    ---
    openapi: "v1 GET /users/{id}"
    ---
    ```
  </Accordion>

  <Accordion title="来自 API 操作台的请求无法正常工作">
    如果你配置了自定义 domain，这可能与反向代理有关。默认情况下，通过 API 操作台发起的请求会先向文档站点的 `/_mintlify/api/request` 路径发送一个 `POST` 请求。如果你将反向代理配置为只允许 `GET` 请求，那么这些请求都会失败。要解决此问题，请将反向代理配置为允许对 `/_mintlify/api/request` 路径的 `POST` 请求。

    或者，如果你的反向代理禁止接受 `POST` 请求，你可以在 `docs.json` 中通过 `api.playground.proxy` 设置，让 Mintlify 直接将请求发送到你的后端。详情请参见[设置文档](/zh/organize/settings-api)。使用此配置时，你必须在服务器上配置 CORS，因为请求是直接来自用户的浏览器，而不是通过你的代理。
  </Accordion>

  <Accordion title="OpenAPI 导航项未生成页面">
    如果你使用的是 OpenAPI 导航配置，但页面未生成，请检查以下常见问题：

    1. **缺少默认 OpenAPI 规范**：请确保在该导航元素上设置了 `openapi` 字段：

    ```json {5}
    "navigation": {
      "groups": [
        {
          "group": "API 参考",
          "openapi": "/path/to/openapi.json",
          "pages": [
            "GET /users",
            "POST /users"
          ]
        }
      ]
    }
    ```

    2. **OpenAPI 规范继承**：如果使用嵌套导航，确保子 groups 继承正确的 OpenAPI 规范，或为其分别指定自己的规范。

    3. **验证问题**：使用 `mint validate` 验证你的 OpenAPI 文档是否有效。
  </Accordion>

  <Accordion title="某些 OpenAPI 操作会出现在导航中，但其他则不会出现">
    1. **隐藏操作**：在你的 OpenAPI 规范中标记为 `x-hidden: true` 的操作不会出现在自动生成的导航中。
    2. **无效操作**：OpenAPI 规范中存在校验错误的操作可能会被跳过。请检查你的 OpenAPI 文档是否有语法错误。
    3. **手动与自动包含**：如果你从某个 OpenAPI 规范中引用了任意端点，只有被明确引用的操作会显示在导航中，其他页面不会自动添加。这也包括在子导航元素中被引用的操作。
  </Accordion>

  <Accordion title="Authorization 字段的描述过于通用或没有帮助">
    Mintlify 会根据安全方案类型自动为 API 操作台中的 `Authorization` 字段生成描述。你可以在 OpenAPI 规范的安全方案中添加 `description` 来覆盖它。

    ```json {7}
    {
      "components": {
        "securitySchemes": {
          "bearerAuth": {
            "type": "http",
            "scheme": "bearer",
            "description": "在 [dashboard](https://example.com/dashboard) 中获取的 API key。发送时使用 `Bearer <key>` 的形式。"
          }
        }
      }
    }
    ```

    `description` 支持 Markdown，并会替换所有使用该安全方案的端点上自动生成的文本。
  </Accordion>

  <Accordion title="混合导航（OpenAPI 与 MDX 页面）工作异常">
    在导航中将 OpenAPI 操作与常规文档页面结合使用时：

    1. **文件冲突**：同一操作不能同时存在 `MDX` 文件和导航条目。比如，如果你有 `get-users.mdx`，就不要在导航中再包含 `"GET /users"`。如果你需要一个与该操作同名的文件，请为该端点使用 `x-mint` 扩展，让 href 指向其他位置。
    2. **路径解析**：与 OpenAPI 操作不匹配的导航条目将被视为文件路径。请确保你的 `MDX` 文件位于预期的位置。
    3. **大小写敏感**：OpenAPI 操作匹配区分大小写。请确保在导航条目中 HTTP 方法使用大写。
  </Accordion>
</AccordionGroup>