mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
be2090200f
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
119 lines
3.2 KiB
Plaintext
119 lines
3.2 KiB
Plaintext
---
|
||
title: "将 MDX API 页面迁移到 OpenAPI 导航"
|
||
sidebarTitle: "从 MDX 迁移到 OAS"
|
||
description: "迁移到通过 OpenAPI 自动生成、并具有灵活导航结构的文档。"
|
||
keywords: ["API 迁移", "OpenAPI 迁移", "x-mint 扩展"]
|
||
---
|
||
|
||
如果你目前为每个 API 端点使用独立的 MDX 页面，你可以迁移到根据 OpenAPI 规范自动生成页面，同时仍然保留单个页面的自定义能力。这样可以帮助你减少需要维护的文件数量，并提升 API 文档的一致性。
|
||
|
||
你可以在 OpenAPI 规范中为每个端点定义 metadata 和 content，并在导航结构中按照你的需求组织这些端点。
|
||
|
||
<div id="migration-steps">
|
||
## 迁移步骤
|
||
</div>
|
||
|
||
<Steps>
|
||
<Step title="准备你的 OpenAPI 规范。">
|
||
确保你的 OpenAPI 规范是有效的，并包含你想要编写文档的所有端点。
|
||
|
||
对于任何你想自定义元数据或内容的端点，为该端点添加 `x-mint` 扩展。更多详情参见 [x-mint extension](/zh/api-playground/openapi-setup#customize-your-endpoint-pages)。
|
||
|
||
对于任何你想从文档中排除的端点，为该端点添加 `x-hidden` 扩展。
|
||
|
||
<Info>
|
||
使用 [Swagger Editor](https://editor.swagger.io/) 或 [Mint CLI](https://www.npmjs.com/package/mint) 校验你的 OpenAPI 文件。
|
||
</Info>
|
||
</Step>
|
||
|
||
<Step title="更新你的导航结构。">
|
||
在你的 `docs.json` 中，将对 MDX 页面的引用替换为 OpenAPI 端点。
|
||
|
||
```json
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "API Reference",
|
||
"openapi": "/path/to/openapi.json",
|
||
"pages": [
|
||
"overview",
|
||
"authentication",
|
||
"introduction",
|
||
"GET /health",
|
||
"quickstart",
|
||
"POST /users",
|
||
"GET /users/{id}",
|
||
"advanced-features"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
</Step>
|
||
|
||
<Step title="移除旧的 MDX 文件。">
|
||
在确认你的新导航正常工作后，移除不再需要的 MDX 端点文件。
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="navigation-patterns">
|
||
## 导航模式
|
||
</div>
|
||
|
||
你可以自定义 API 文档在导航中的显示方式。
|
||
|
||
<div id="mixed-content-navigation">
|
||
### 混合内容导航
|
||
</div>
|
||
|
||
将自动生成的 API 页面与其他页面结合使用：
|
||
|
||
```json
|
||
"navigation": {
|
||
"groups": [
|
||
{
|
||
"group": "API 参考",
|
||
"openapi": "openapi.json",
|
||
"pages": [
|
||
"api/overview",
|
||
"GET /users",
|
||
"POST /users",
|
||
"api/authentication"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
<div id="multiple-api-versions">
|
||
### 多个 API 版本
|
||
</div>
|
||
|
||
使用 Tabs 或 groups 来组织不同的 API 版本：
|
||
|
||
```json
|
||
"navigation": {
|
||
"tabs": [
|
||
{
|
||
"tab": "API v1",
|
||
"openapi": "specs/v1.json"
|
||
},
|
||
{
|
||
"tab": "API v2",
|
||
"openapi": "specs/v2.json"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
<div id="when-to-use-individual-mdx-pages">
|
||
## 何时使用单独的 MDX 页面
|
||
</div>
|
||
|
||
在以下情况下，可以保留单独的 MDX 页面：
|
||
|
||
* 每个接口需要大量自定义内容，例如 React 组件或篇幅较长的示例。
|
||
* 需要独特的页面布局。
|
||
* 想在特定接口上尝试实验性的文档编写方式。
|
||
|
||
对于大多数场景，OpenAPI 导航在可维护性和一致性方面表现更好。 |