> ## 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.

# 疑难排查

> API 参考的常见问题

如果你的 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/omer-914cc1c6/AiL60EGGBeap42Y0/images/convert-oas-3.png?fit=max&auto=format&n=AiL60EGGBeap42Y0&q=85&s=b27984c1f018728eaca6ebfdd8720378" alt="" width="1454" height="592" data-path="images/convert-oas-3.png" />
    </Frame>
  </Accordion>

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

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

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

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

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

    另一个常见问题是文件名拼写错误。如果你在 `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` 请求，你可以按照[设置文档](/zh/settings#param-proxy)中的说明，在 `docs.json` 里的 `api.playground.proxy` 设置中让 Mintlify 将请求直接发送到你的后端。使用此配置时，你需要在服务器上配置 CORS，因为请求将直接来自用户的浏览器，而不是通过代理。
  </Accordion>

  <Accordion title="OpenAPI navigation 条目未生成页面">
    如果你正在使用 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 openapi-check <path-to-openapi-file>` 验证你的 OpenAPI 文档是否有效。
  </Accordion>

  <Accordion title="某些 OpenAPI 操作会出现在导航中，但另外一些不会">
    1. **隐藏的操作**：在你的 OpenAPI 规范中标记为 `x-hidden: true` 的操作将不会出现在自动生成的导航中。
    2. **无效的操作**：在 OpenAPI 规范中存在校验错误的操作可能会被跳过。请检查你的 OpenAPI 文档是否存在语法错误。
    3. **手动 vs 自动包含**：如果你从某个 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>