跳转到主要内容
如果你的 API 页面显示异常，请检查以下常见的配置问题：
在这种情况下，很可能是 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：
这通常是由于页面元数据中的 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}"
---
如果你已配置自定义域名，问题可能出在反向代理上。默认情况下，通过 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规范继承：如果使用嵌套导航，请确保子分组继承正确的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 方法使用大写。