故障排查

API 参考中的常见问题

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

All of my OpenAPI pages are completely blank

在这种情况下，很可能是 Mintlify 找不到你的 OpenAPI 文档，或者该文档无效。

在本地运行 mint dev 应该能暴露出其中一些问题。

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

1. 访问此验证器
2. 切换到“Validate text”选项卡
3. 粘贴你的 OpenAPI 文档
4. 点击“Validate it!”

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

另外，Mintlify 不支持 OpenAPI 2.0。如果你的文档使用该版本规范，可能会遇到此问题。你可以在 editor.swagger.io（Edit > Convert to OpenAPI 3）将文档转换为 OpenAPI 3：

One of my OpenAPI pages is completely blank

这通常是由于页面元数据中的 openapi 字段拼写错误导致的。请确保 HTTP 方法和路径与 OpenAPI 文档中的 HTTP 方法和路径完全一致。

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

get-user.mdx

---
openapi: "GET /users/{id}/"
---

openapi.yaml

paths:
  "/users/{id}":
    get: ...

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

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

api-reference/v1/users/get-user.mdx

---
openapi: "v1 GET /users/{id}"
---

Requests from the API Playground don't work

如果你配置了自定义域名，这可能是你的反向代理导致的问题。默认情况下，通过 API 操作台发起的请求会首先向文档站点的 /_mintlify/api/request 路径发送一个 POST 请求。如果你的反向代理仅允许 GET 请求，那么这些请求都会失败。要解决此问题，请将反向代理配置为允许对 /_mintlify/api/request 路径的 POST 请求。

或者，如果你的反向代理无法接受 POST 请求，你可以按照设置文档中的说明，在 docs.json 中通过 api.playground.proxy 设置，将 Mintlify 配置为直接向你的后端发送请求。使用此配置时，你需要在服务器上配置 CORS，因为请求将直接来自用户的浏览器，而不是通过你的代理。

OpenAPI navigation entries are not generating pages

如果你使用的是 OpenAPI 导航配置，但页面没有生成，请检查以下常见问题：

1. 缺少默认 OpenAPI 规范：确保在导航元素中设置了 openapi 字段：

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

2. OpenAPI 规范继承：如果使用嵌套导航，确保子分组继承到正确的 OpenAPI 规范，或为其单独指定。

3. 校验问题：使用 mint openapi-check <path-to-openapi-file> 校验你的 OpenAPI 文档是否有效。

Some OpenAPI operations appear in navigation but others don't

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

Mixed navigation (OpenAPI and MDX pages) not working correctly

在导航中同时使用 OpenAPI 操作与常规文档页面时：

1. 文件冲突：同一操作不能既有一个 MDX 文件又在导航中有对应条目。例如，如果已有 get-users.mdx，请不要在导航中再添加 "GET /users"。如果确需使用与某个操作同名的文件，请在该端点上使用 x-mint 扩展，将 href 指向其他位置。
2. 路径解析：与 OpenAPI 操作不匹配的导航条目将按文件路径处理。请确保相应的 MDX 文件存在于预期位置。
3. 大小写敏感：OpenAPI 操作匹配区分大小写。请确保导航条目中的 HTTP 方法使用大写。