跳转到主要内容
如果你的 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. 手动与自动包含：如果你从某个 OpenAPI 规范中引用了任何端点，只有被显式引用的操作会显示在导航中。不会自动添加其他页面。这也包括在子导航元素中被引用的操作。
在导航中将 OpenAPI 操作与常规文档页面一起使用时：
  1. 文件冲突：同一操作不能同时存在一个 MDX 文件和一个导航条目。例如，如果你有 get-users.mdx，请不要在导航中同时包含 "GET /users"。如果确实需要创建与某个操作同名的文件，请为该端点使用 x-mint 扩展，让 href 指向其他位置。
  2. 路径解析：与 OpenAPI 操作不匹配的导航条目将被视为文件路径。请确保你的 MDX 文件位于预期位置。
  3. 大小写敏感：OpenAPI 操作匹配区分大小写。请确保在导航条目中将 HTTP 方法写为大写。
⌘I