mintlify__docs/zh/guides/migrating-from-mdx.mdx

---
title: "将 MDX API 页面迁移到 OpenAPI 导航"
sidebarTitle: "从 MDX 迁移到 OAS"
description: "迁移到通过 OpenAPI 自动生成、并具有灵活导航结构的文档。"
keywords: ["API 迁移", "mint migrate-mdx", "OpenAPI 迁移", "x-mint 扩展"]
---

如果你目前为每个 API 端点使用独立的 MDX 页面，你可以迁移到根据 OpenAPI 规范自动生成页面，同时仍然保留单个页面的自定义能力。这样可以帮助你减少需要维护的文件数量，并提升 API 文档的一致性。

你可以在 OpenAPI 规范中为每个端点定义 metadata 和 content，并在导航结构中按照你的需求组织这些端点。

<div id="cli-migration">
  ## CLI 迁移
</div>

推荐使用 `mint migrate-mdx` 命令，将 MDX 端点页面迁移为自动生成的页面。

此命令将：

* 解析你的 `docs.json` 导航结构。
* 识别会生成 OpenAPI 端点页面的 MDX 页面。
* 从 MDX 文件中提取内容，并将其移至 OpenAPI 规范中的 `x-mint` 扩展。
* 更新你的 `docs.json`，使其直接引用 OpenAPI 端点而非 MDX 文件。
* 删除原有的 MDX 端点文件。

<Info>
  如果你已为某个端点定义了 `x-mint`，同时还有一个包含该端点内容的 MDX 页面，则该 MDX 内容会覆盖现有的 `x-mint` 设置。

  如果同一端点存在多个内容不同的 MDX 页面，脚本将采用在你的 `docs.json` 中出现最靠后的页面内容。

  迁移工具不支持在应用更改前预览更改。
</Info>

<Steps>
  <Step title="准备你的 OpenAPI 规范。">
    确保你的 OpenAPI 规范有效，并包含你要文档化的所有端点。

    需要迁移的任何 MDX 页面必须在 `openapi:` frontmatter 中引用某个端点。

    <Tip>
      使用 [Swagger Editor](https://editor.swagger.io/) 或 [Mint CLI](https://www.npmjs.com/package/mint) 验证你的 OpenAPI 文件。
    </Tip>
  </Step>

  <Step title="安装 Mint CLI">
    如有需要，请安装或更新 [Mint CLI](/zh/installation)。
  </Step>

  <Step title="运行迁移命令。">
    ```bash
    mint migrate-mdx
    ```
  </Step>
</Steps>

<div id="manual-migration-steps">
  ## 手动迁移步骤
</div>

<Steps>
  <Step title="准备你的 OpenAPI 规范。">
    确保你的 OpenAPI 规范是有效的，并包含你想要编写文档的所有端点。

    对于任何你想自定义元数据或内容的端点，为该端点添加 `x-mint` 扩展。更多详情参见 [x-mint extension](/zh/api-playground/openapi-setup#x-mint-extension)。

    对于任何你想从文档中排除的端点，为该端点添加 `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 导航在可维护性和一致性方面表现更好。