如何在 Mintlify 中导入 OpenAPI 规范以生成交互式 API 参考文档

Mintlify 能够将 OpenAPI 3.0 与 3.1 规范（支持 JSON 与 YAML 格式）直接转换为结构清晰、具备交互能力的现代化 API 参考文档。开发与技术写作团队无需手动维护繁琐的请求参数表格、请求头说明或响应字段模型，Mintlify 会自动解析规范文件，生成多语言代码示例生成器，并提供允许开发者在浏览器中直接发起请求测试的实时 API 控制台（Playground）。

在架构设计上，Mintlify 采用文档即代码（Docs-as-code）的工作模式。OpenAPI 规范文件与 Markdown 文档一同保存在 Git 仓库中，由核心配置文件（docs.json，早期版本为 mint.json）统筹全局结构。团队可以根据实际需要选择两种接入路径：一是零人工维护的全自动文档生成，由规范文件驱动整套参考手册；二是将 OpenAPI 接口精准绑定到特定 MDX 页面中，在保留自动化参数与测试控制台的同时补充业务教程、架构指引与深度说明。

前置条件与规范要求

在配置 Mintlify 之前，需确保接口规范文件符合平台要求：

• 规范版本： Mintlify 原生支持 OpenAPI Specification (OAS) 3.0 与 3.1 版本。若现有规范仍停留在 Swagger 2.0，需先将其转换为 OpenAPI 3.0。
• 文件格式： 支持标准的 JSON（.json）与 YAML（.yaml 或 .yml）。
• 引用限制（$ref）： Mintlify 支持单文件内的内部引用（如 $ref: '#/components/schemas/User'），但不支持跨文件的外部模式引用。如果团队的规范拆分在多个独立文件中，在导入 Mintlify 前必须先使用工具（例如 Redocly CLI 或 @apidevtools/swagger-cli）将其打包整合为单一文件。

第一步：放置 OpenAPI 规范文件

团队可以通过本地仓库归档或远程 URL 两种方式接入规范文件：

1. 本地仓库托管（推荐）： 将规范文件直接提交至文档仓库内。常见做法是存放在项目根目录（例如 openapi.json、openapi.yaml）或专用的接口目录中（例如 api-reference/openapi.json 或 specs/v1.yaml）。

2. 托管远程 URL： 如果后端 CI/CD 流水线会自动构建并发布最新的 OpenAPI 文件至对象存储或 CDN，可以直接在配置中指定 HTTPS 链接（例如 https://api.example.com/specs/openapi.json）。在线上生产环境中，远程规范必须使用 HTTPS 协议。

第二步：在 docs.json 中配置导航

要在文档左侧侧边栏中渲染 API 参考页面，需在 docs.json 的 navigation 节点下进行关联。

方案 A：全自动生成参考文档

如果希望 Mintlify 自动提取规范中的所有路径，并根据 OpenAPI 的 tags 标签完成分组与页面渲染，只需在导航标签或分组中直接声明规范路径：

{
  "$schema": "https://mintlify.com/docs.json",
  "name": "Acme API Docs",
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "入门指南",
            "pages": ["introduction", "quickstart"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "openapi": "openapi.json"
      }
    ]
  }
}

在此配置下，Mintlify 会自动扫描 paths 下定义的所有接口，提取 HTTP 请求方法、接口摘要、详细描述、参数列表与响应结构，无需编写任何 MDX 文件即可生成整套 API 浏览目录。

多规范协同管理

若系统包含多个独立微服务或拆分了不同的 API 版本，可以在 openapi 属性中传入文件路径数组：

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

第三步：借助 MDX 页面实现精细化文档定制

虽然全自动模式省心省力，但技术写作者通常需要在特定接口旁补充业务背景、前置依赖、频控警告或架构时序图。Mintlify 支持通过 MDX 的 Frontmatter 属性将页面与具体接口强绑定。

1. 将 MDX 页面绑定到指定接口

新建一个 MDX 文件（例如 api-reference/users/create.mdx），在开头的 Frontmatter 中通过 openapi 字段声明对应的 HTTP 方法与路由：

---
title: "创建用户"
sidebarTitle: "创建用户"
description: "在当前组织下注册新的用户账户"
openapi: "POST /v1/users"
---

## 业务说明

在调用此接口前，请确保客户端已完成鉴权，并拥有 `users:write` 权限作用域。

<Warning>
  用户的电子邮箱在组织内必须唯一。如果传入已存在的邮箱地址，系统将返回 `409 Conflict` 错误。
</Warning>

## Webhook 回调通知

用户成功创建后，系统将自动触发 `user.created` 事件，并向您配置的 Webhook 端点推送数据通知。

Mintlify 解析到 POST /v1/users 后，会自动将规范中对应的请求构建器、请求参数说明和响应 Schema 注入到当前页面中，并与自定义的 MDX 正文融为一体。

如果项目中引入了多个规范文件，为避免路由冲突，需在前面注明规范文件路径：

---
title: "创建用户"
openapi: "specs/v1/auth.json POST /v1/users"
---

2. 使用 Mintlify 官方工具批量生成 MDX 模板

当现有接口数量庞大且希望逐个细化时，可以使用官方提供的抓取生成脚本：

npx @mintlify/scraping@latest openapi-file ./openapi.json -o api-reference

该命令会自动解析规范并在 api-reference 目录下生成各接口对应的独立 MDX 文件，且均已配置好相应的 Frontmatter 属性，方便团队快速上手编辑。

第四步：配置交互式 API 控制台（Playground）

Mintlify 的实时控制台允许开发者在文档页面内直接填参并发起真实 HTTP 请求。为了让测试体验更顺畅，需在规范文件与配置中做好以下设定：

1. 指定 API 基础服务器地址（Base URL）

Mintlify 会直接读取 OpenAPI 规范中的 servers 数组作为请求目标地址：

servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: https://staging.api.example.com/v1
    description: 测试沙箱

当定义了多个服务器地址时，控制台界面会自动展示环境下拉切换菜单。

2. 配置鉴权凭证与默认测试值

在规范的 components.securitySchemes 中声明认证方案，控制台便会自动呈现对应的输入框（支持 Bearer Token、API Key、Basic Auth 等）：

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 请输入您的 API 访问令牌
security:
  - bearerAuth: []

为了方便读者快速试用沙箱接口，可以在安全方案中增加 x-default 扩展字段以提供预置测试密钥：

{
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "x-default": "demo_pk_live_testing123"
      }
    }
  }
}

3. 解决跨域资源共享（CORS）问题

由于交互式控制台发起的请求来自读者的浏览器客户端，后端接口服务器必须正确响应跨域预检与请求头，否则浏览器将拦截网络通信：

• Access-Control-Allow-Origin: *（或您的文档专属域名）
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
• Access-Control-Allow-Headers: Authorization, Content-Type, X-API-Key

如果服务端未放行 OPTIONS 预检请求，会导致控制台测试失败，即便本地 curl 能够正常访问。

第五步：利用 OpenAPI Overlays 无侵入式调整规范

技术写作者常常面临一个现实痛点：后端代码自动生成的规范往往包含内部未公开接口，或者字段描述晦涩，而直接修改源码或维护一份分叉的规范又极易失步。Mintlify 支持 OpenAPI Overlay 规范（v1.1.0），允许在文档构建时通过补丁文件无损修饰规范。

创建叠加层文件（例如 overlays/public-filter.yaml），使用标准的 JSONPath 语法执行 update、remove 或 copy 操作：

overlay: 1.1.0
info:
  title: 公开文档修饰配置
  version: 1.0.0
extends: ./openapi.json
actions:
  - target: $.info.description
    update: "欢迎查阅 Acme 官方开发者文档，您可以在此了解接口细节并进行在线调试。"
  - target: $.paths['/internal/system-health']
    remove: true
  - target: $.paths['/v1/billing'].post.summary
    update: "创建周期性扣费订阅"

随后在 docs.json 中关联该叠加层：

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": {
          "source": "openapi.json",
          "overlays": ["overlays/public-filter.yaml"]
        }
      }
    ]
  }
}

Mintlify 在编译站点时会自动应用补丁，既隐藏了内部路由、优化了对外措辞，又保障了上游工程源码规范的纯粹性。

第六步：本地调试与 CI/CD 自动化校验

在推送至生产发布前，使用 Mintlify CLI 在本地进行实时预览与合法性校验：

1. 安装并启动开发预览服务器：

   npm i -g mintlify
   mint dev
   

2. 调试本地正在运行的规范服务： 如果规范由本地后端接口动态生成（例如 http://localhost:8000/openapi.json），启动时需附加授权参数：

   mint dev --local-schema
   

3. 运行严格格式验证： 排查断裂的模式引用、缺漏的响应结构与语法异常：

   mint validate
   

4. 集成持续集成（CI）流水线： 将 mint validate 纳入 GitHub Actions 或 GitLab CI 流水线中。每当研发提交新的接口定义时，CI 会自动校验引用完整性，有效防止有缺陷的规范破坏线上文档。

参考资料

• OpenAPI setup - Mintlify
• API playground overview - Mintlify
• Navigation - Mintlify
• Troubleshooting - Mintlify