如果你目前为 API 端点使用独立的 MDX 页面，你可以迁移到基于 OpenAPI 规范自动生成页面，同时保留单个页面的自定义能力。这样可以减少需要维护的文件数量，并提升 API 文档的一致性。 你可以在 OpenAPI 规范中为每个端点定义元数据和内容，并在导航中按需组织这些端点。

​
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 页面必须在 frontmatter 中使用 openapi: 引用某个端点。
使用 Swagger Editor 或 Mint CLI 验证你的 OpenAPI 文件。
2

安装 Mint CLI

按需安装或更新 Mint CLI。
3

运行迁移命令。

mint migrate-mdx

​
手动迁移步骤

1

准备你的 OpenAPI 规范。

确保你的 OpenAPI 规范有效，并包含你希望记录的所有端点。对于需要自定义元数据或内容的端点，在该端点添加 x-mint 扩展。详见 x-mint 扩展。对于希望从文档中排除的端点，在该端点添加 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 Reference",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}

​
多个 API 版本

使用选项卡或分组来组织不同的 API 版本： 
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2", 
      "openapi": "specs/v2.json"
    }
  ]
}

​
何时使用独立的 MDX 页面

在以下情况下，建议保留独立的 MDX 页面：
  • 每个端点需要大量自定义内容，例如使用 React 组件或提供较长的示例。
  • 需要自定义的页面布局。
  • 针对特定端点尝试实验性的文档编写方式。
对于大多数场景，使用 OpenAPI 导航能带来更好的可维护性与一致性。