> ## 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 参考中的常见问题

如果你的 API 页面显示异常，请检查以下常见的配置问题：

<AccordionGroup>
  <Accordion title="我的所有 OpenAPI规范 页面都是空白的">
    在这种情况下，很可能是 Mintlify 找不到你的 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）将文档转换为 OpenAPI 3：

    <Frame>
      <img src="https://mintcdn.com/mintlify-mintlify-add-hello-world-quickstart-48843/FYO7l_4g6ReiCSAk/images/convert-oas-3.png?fit=max&auto=format&n=FYO7l_4g6ReiCSAk&q=85&s=af1abc18d02cfdce7aaa3782c21a0f70" alt="" width="1454" height="592" data-path="images/convert-oas-3.png" />
    </Frame>
  </Accordion>

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

    下面是一个可能出现问题的示例：

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

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

    请注意，`openapi` 字段中的路径带有末尾斜杠，而 OpenAPI 文档中的路径没有。

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

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

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

    或者，如果你的反向代理无法接受 `POST` 请求，你可以在 `docs.json` 中通过 `api.playground.proxy` 设置，让 Mintlify 直接向你的后端发送请求，详见[设置文档](/zh/settings#param-proxy)。使用该配置时，你需要在服务器上配置 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规范继承**：如果使用嵌套导航，请确保子分组继承正确的OpenAPI规范，或为其单独指定规范。

    3. **验证问题**：使用 `mint openapi-check <path-to-openapi-file>` 来验证你的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>