将 MDX API 页面迁移到 OpenAPI 导航

将单个 MDX 端点页面更新为通过灵活导航的 OpenAPI 自动生成

如果你目前为 API 端点使用单独的 MDX 页面，可以迁移为基于 OpenAPI 规范自动生成页面，同时保留单页的自定义灵活性。这样可以减少需要维护的文件数量，并提升 API 文档的一致性。

你可以在 OpenAPI 规范中为每个端点定义 metadata 和 content，并在导航中将端点组织到所需的位置。

​

CLI 迁移

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

该命令将：

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

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

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

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

1. 准备你的 OpenAPI 规范。

   确保你的 OpenAPI 规范有效，并包含你要编写文档的所有端点。

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

   使用 Swagger Editor 或 Mint CLI 验证你的 OpenAPI 文件。

2. 安装 Mint CLI

   如有需要，请安装或更新 Mint CLI。

3. 运行迁移命令。

   mint migrate-mdx
   

​

手动迁移步骤

1. 准备你的 OpenAPI 规范。

   确保你的 OpenAPI 规范有效，并包含你希望记录的所有端点。

   对于需要自定义 metadata 或 content 的端点，请在该端点添加 x-mint 扩展。更多详情参见 x-mint extension。

   对于需要从文档中排除的端点，请在该端点添加 x-hidden 扩展。

   使用 Swagger Editor 或 Mint CLI 验证你的 OpenAPI 文件。

2. 更新你的导航结构。

   在你的 docs.json 中，将 MDX 页面引用替换为 OpenAPI 端点。

   "navigation": {
     "groups": [
       {
         "group": "API Reference",
         "openapi": "/path/to/openapi.json",
         "pages": [
           "overview",
           "authentication",
           "introduction",
           "GET /health",
           "quickstart", 
           "POST /users",
           "GET /users/{id}",
           "advanced-features"
         ]
       }
     ]
   }
   
3. 移除旧的 MDX 文件。

   在确认新的导航正常工作后，删除不再需要的 MDX 端点文件。

​

导航模式

你可以自定义 API 文档在导航中的呈现方式。

​

混合内容导航

将自动生成的 API 页面与其他页面结合使用：

"navigation": {
  "groups": [
    {
      "group": "API 参考",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}

​

多个 API 版本

使用选项卡或 groups 来组织不同的 API 版本：

"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2",
      "openapi": "specs/v2.json"
    }
  ]
}

​

何时使用单独的 MDX 页面

在以下情况下，建议保留单独的 MDX 页面：

• 每个端点需要大量自定义内容，例如 React 组件或较长的示例。
• 需要独特的页面布局。
• 针对特定端点尝试实验性的文档写法。

对于大多数用例，OpenAPI 导航能提供更好的可维护性和一致性。