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

# 故障排查

> 排查 API 演练场配置中的常见问题，包括 OpenAPI 验证错误、缺失的端点和身份验证问题。

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

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

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

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

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

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

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

    <Frame>
      <img src="https://mintcdn.com/smartac-mintlify-04d11f81/PoSB_e4A8nnwIWQ5/images/convert-oas-3.png?fit=max&auto=format&n=PoSB_e4A8nnwIWQ5&q=85&s=ee44efbd8a7807fbfd554412d2d5464b" alt="展开 Edit 菜单并高亮“Convert to OpenAPI 3”菜单项的 Swagger Editor 截图。" width="1454" height="592" data-path="images/convert-oas-3.png" />
    </Frame>
  </Accordion>

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

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

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

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

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

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

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

    ```mdx api-reference/v1/users/get-user.mdx theme={null}
    ---
    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} theme={null}
    "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="混合导航（OpenAPI 与 MDX 页面）工作异常">
    在导航中将 OpenAPI 操作与常规文档页面结合使用时：

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