跳转到主要内容
如果你的 API 页面显示异常，请先检查以下常见的配置问题：
在这种情况下，很可能是 Mintlify 找不到你的 OpenAPI 文档，或者你的 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）：
这通常是由于页面 metadata 中的 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，你的 metadata 可能如下所示：
api-reference/v1/users/get-user.mdx
---
openapi: "v1 GET /users/{id}"
---
如果你配置了自定义 domain，问题可能出在你的反向代理上。默认情况下，通过 API 操作台发起的请求会先向文档站点的 /_mintlify/api/request 路径发送一个 POST 请求。如果你的反向代理被设置为只允许 GET 请求，这些请求都会失败。要解决此问题，请将反向代理配置为允许对 /_mintlify/api/request 路径的 POST 请求。另外，如果你的反向代理不允许接受 POST 请求，你可以按照设置文档中的说明，在 docs.json 里的 api.playground.proxy 设置中让 Mintlify 将请求直接发送到你的后端。使用此配置时，你需要在服务器上配置 CORS，因为请求将直接来自用户的浏览器，而不是通过代理。
如果你正在使用 OpenAPI 导航配置，但页面未生成，请检查以下常见问题：
  1. 缺少默认 OpenAPI 规范：请确保已为该导航元素设置 openapi 字段：
"navigation": {
  "groups": [
    {
      "group": "API 参考",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "GET /users",
        "POST /users"
      ]
    }
  ]
}
  1. OpenAPI 规范继承：如果使用嵌套导航，请确保子 groups 继承正确的 OpenAPI 规范，或为它们各自指定规范。
  2. 验证问题：使用 mint openapi-check <path-to-openapi-file> 验证你的 OpenAPI 文档是否有效。
  1. 隐藏的操作：在你的 OpenAPI 规范中标记为 x-hidden: true 的操作将不会出现在自动生成的导航中。
  2. 无效的操作：在 OpenAPI 规范中存在校验错误的操作可能会被跳过。请检查你的 OpenAPI 文档是否存在语法错误。
  3. 手动 vs 自动包含：如果你从某个 OpenAPI 规范中引用了任意端点，只有被明确引用的操作会出现在导航中。不会自动添加其他页面。这也包括在子导航元素中被引用的操作。
在导航中将 OpenAPI 操作与常规文档页面结合使用时：
  1. 文件冲突：同一操作不能同时存在一个 MDX 文件和一个导航条目。比如，如果你有 get-users.mdx，就不要在导航中同时包含 "GET /users"。如果需要创建与某个操作同名的文件，请为该端点使用 x-mint 扩展，使 href 指向其他位置。
  2. 路径解析：与 OpenAPI 操作不匹配的导航条目将被视为文件路径。请确保你的 MDX 文件位于预期位置。
  3. 大小写敏感：OpenAPI 操作匹配区分大小写。请确保在导航条目中 HTTP 方法使用大写。
⌘I