跳转到主要内容
如果你的 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）：
展开 Edit 菜单并高亮“Convert to OpenAPI 3”菜单项的 Swagger Editor 截图。
这通常是由于页面 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. 手动与自动包含：如果你从某个 OpenAPI 规范中引用了任意端点，只有被明确引用的操作会显示在导航中，其他页面不会自动添加。这也包括在子导航元素中被引用的操作。
在导航中将 OpenAPI 操作与常规文档页面结合使用时：
  1. 文件冲突：同一操作不能同时存在 MDX 文件和导航条目。比如，如果你有 get-users.mdx，就不要在导航中再包含 "GET /users"。如果你需要一个与该操作同名的文件，请为该端点使用 x-mint 扩展，让 href 指向其他位置。
  2. 路径解析：与 OpenAPI 操作不匹配的导航条目将被视为文件路径。请确保你的 MDX 文件位于预期的位置。
  3. 大小写敏感：OpenAPI 操作匹配区分大小写。请确保在导航条目中 HTTP 方法使用大写。
⌘I