mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
3bebd828f6
* docs: sync es/fr/zh translations with recent English updates * docs: tighten translated SEO metadata and fix register consistency --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
111 lines
5.6 KiB
Plaintext
111 lines
5.6 KiB
Plaintext
---
|
||
title: "故障排查"
|
||
description: "排查 API 演练场配置中的常见问题，包括 OpenAPI 验证错误、缺失的端点和身份验证问题。"
|
||
keywords: ["API 故障排查", "OpenAPI 无效", "配置问题"]
|
||
boost: 3
|
||
---
|
||
|
||
如果你的 API 页面显示不正确，请先检查以下常见配置问题。
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="我的所有 OpenAPI 页面都是空白的">
|
||
在这种情况下，很可能是 Mintlify 找不到你的 OpenAPI 文档，或者你的 OpenAPI 文档无效。
|
||
|
||
在本地运行 `mint dev` 通常能暴露出其中一些问题。
|
||
|
||
要验证你的 OpenAPI 文档是否通过校验：
|
||
|
||
1. 访问[此校验器](https://editor.swagger.io/)。
|
||
2. 切换到 **Validate text** 标签页。
|
||
3. 粘贴你的 OpenAPI 文档。
|
||
4. 点击 **Validate it!**
|
||
|
||
如果下方出现的文本框带有绿色边框，说明你的文档已通过校验。
|
||
这是 Mintlify 用于校验 OpenAPI 文档的同一套校验包，因此如果你的文档在这里通过校验，很大概率问题出在其他地方。
|
||
|
||
此外，Mintlify 不支持 OpenAPI 2.0。如果你的文档使用该版本规范，可能会遇到此问题。你可以在 [editor.swagger.io](https://editor.swagger.io/) 上转换文档 (Edit > Convert to OpenAPI 3) ：
|
||
|
||
<Frame>
|
||
|
||
</Frame>
|
||
</Accordion>
|
||
|
||
<Accordion title="我的某个 OpenAPI 页面是完全空白的">
|
||
这通常是由于页面 metadata 中的 `openapi` 字段拼写错误导致的。请确保
|
||
HTTP 方法和路径与 OpenAPI 文档中的 HTTP 方法和路径一致。
|
||
|
||
<Note>
|
||
Mintlify 会自动解析 `openapi` 引用与 OpenAPI 规范之间尾部斜杠的差异。
|
||
例如，`GET /users/{id}/` 可以匹配规范中的路径 `/users/{id}`。
|
||
</Note>
|
||
|
||
下面是一个可能出错的示例：
|
||
|
||
```mdx get-user.mdx
|
||
---
|
||
openapi: "GET /user/{id}"
|
||
---
|
||
```
|
||
|
||
```yaml openapi.yaml
|
||
paths:
|
||
"/users/{id}":
|
||
get: ...
|
||
```
|
||
|
||
请注意，`openapi` 字段中的路径是 `/user/{id}` (单数)，而 OpenAPI 文档中的路径是 `/users/{id}` (复数)。
|
||
|
||
另一个常见问题是文件名拼写错误。如果你在 `openapi` 字段中指定了某个特定的 OpenAPI 文档，请确保文件名正确。例如，如果你有两个 OpenAPI 文档 `openapi/v1.json` 和 `openapi/v2.json`，你的 metadata 可能如下所示：
|
||
|
||
```mdx api-reference/v1/users/get-user.mdx
|
||
---
|
||
openapi: "v1 GET /users/{id}"
|
||
---
|
||
```
|
||
</Accordion>
|
||
|
||
<Accordion title="来自 API 操作台的请求无法正常工作">
|
||
如果你配置了自定义 domain，这可能与反向代理有关。默认情况下，通过 API 操作台发起的请求会先向文档站点的 `/_mintlify/api/request` 路径发送一个 `POST` 请求。如果你将反向代理配置为只允许 `GET` 请求，那么这些请求都会失败。要解决此问题，请将反向代理配置为允许对 `/_mintlify/api/request` 路径的 `POST` 请求。
|
||
|
||
或者，如果你的反向代理禁止接受 `POST` 请求，你可以在 `docs.json` 中通过 `api.playground.proxy` 设置，让 Mintlify 直接将请求发送到你的后端。详情请参见[设置文档](/zh/organize/settings-api)。使用此配置时，你必须在服务器上配置 CORS，因为请求是直接来自用户的浏览器，而不是通过你的代理。
|
||
</Accordion>
|
||
|
||
<Accordion title="OpenAPI 导航项未生成页面">
|
||
如果你使用的是 OpenAPI 导航配置，但页面未生成，请检查以下常见问题：
|
||
|
||
1. **缺少默认 OpenAPI 规范**：请确保在该导航元素上设置了 `openapi` 字段：
|
||
|
||
```json {5}
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "API 参考",
|
||
"openapi": "/path/to/openapi.json",
|
||
"pages": [
|
||
"GET /users",
|
||
"POST /users"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
2. **OpenAPI 规范继承**：如果使用嵌套导航，确保子 groups 继承正确的 OpenAPI 规范，或为其分别指定自己的规范。
|
||
|
||
3. **验证问题**：使用 `mint validate` 验证你的 OpenAPI 文档是否有效。
|
||
</Accordion>
|
||
|
||
<Accordion title="某些 OpenAPI 操作会出现在导航中，但其他则不会出现">
|
||
1. **隐藏操作**：在你的 OpenAPI 规范中标记为 `x-hidden: true` 的操作不会出现在自动生成的导航中。
|
||
2. **无效操作**：OpenAPI 规范中存在校验错误的操作可能会被跳过。请检查你的 OpenAPI 文档是否有语法错误。
|
||
3. **手动与自动包含**：如果你从某个 OpenAPI 规范中引用了任意端点，只有被明确引用的操作会显示在导航中，其他页面不会自动添加。这也包括在子导航元素中被引用的操作。
|
||
</Accordion>
|
||
|
||
<Accordion title="混合导航（OpenAPI 与 MDX 页面）工作异常">
|
||
在导航中将 OpenAPI 操作与常规文档页面结合使用时：
|
||
|
||
1. **文件冲突**：同一操作不能同时存在 `MDX` 文件和导航条目。比如，如果你有 `get-users.mdx`，就不要在导航中再包含 `"GET /users"`。如果你需要一个与该操作同名的文件，请为该端点使用 `x-mint` 扩展，让 href 指向其他位置。
|
||
2. **路径解析**：与 OpenAPI 操作不匹配的导航条目将被视为文件路径。请确保你的 `MDX` 文件位于预期的位置。
|
||
3. **大小写敏感**：OpenAPI 操作匹配区分大小写。请确保在导航条目中 HTTP 方法使用大写。
|
||
</Accordion>
|
||
</AccordionGroup> |