从 Stoplight 迁移到 Apifox 不仅仅是导入一个 OpenAPI 文件，而是迁移一个基于文件的 API 工作流。

对于许多团队来说，Stoplight 项目包含的内容远不止接口：还包括 Git 中的 OpenAPI 规范、Markdown 文档、JSON Schema 数据模型、本地图片、支持的 toc.json 导航配置以及支持的 .stoplight.json 路径设置。

团队可能还在 Postman 中保留了请求示例，在 CI 中编写了测试脚本。如果从 Stoplight 迁移到 Apifox 时仅导入单个 OpenAPI 文件，虽然接口列表得以保留，但整个工作流将不复存在。

Apifox Spec-first 模式 可帮助团队在 Stoplight 迁移过程中将 OpenAPI 文件保留为单一可信源，同时将这些文件连接到更广泛的 API 工作空间，以用于文档、mock、测试、报告、权限和协作。

本指南将介绍如何规划迁移：哪些内容可以保留、哪些需要评审、哪些需要重建，以及如何围绕 OpenAPI 契约进行连接。

有关具体的操作设置步骤，请参阅 Spec-first 模式帮助指南。

为什么 Stoplight 迁移不仅仅是导入 OpenAPI

OpenAPI 文件描述了 API 契约。而 Stoplight 风格的项目通常包含围绕该契约的更多上下文。

常见的项目资产包括：

1. OpenAPI 或 Swagger 文件，通常存储在 reference 或其他配置的目录下；
2. Markdown 文档，通常存储在 docs 下；
3. JSON Schema 数据模型文件，通常存储在 models 下；
4. 文档中引用的本地图片；
5. 用于支持路径配置的 .stoplight.json；
6. 用于支持文档导航输入、分组和排序的 toc.json；
7. Stoplight 标识符，例如 x-stoplight-id 或 x-stoplight.id。

如果迁移只导入一个 OpenAPI 文件，接口虽然迁移了，但项目模型仍然可能丢失。文档可能需要重建，导航可能与之前的项目不匹配，数据模型可能与文档脱节。测试、mock 和请求示例可能仍然留存在其他独立的工具中。

更好的迁移方案应当从代码仓库或文件树开始，而不是从单个规范文件开始。

迁移模型：保留、评审、重建、连接

在开始之前，请确定真正的单一可信源。如果 Git 中的 OpenAPI 文件定义了 API 契约，那么 Spec-first 迁移可以从这些文件开始。如果实际的请求工作流是由 Postman 或 Bruno 集合驱动的，请先解决这种不匹配。

最稳妥的迁移计划并不是“保留一切”。Stoplight 项目中可能包含某些特定于该产品的功能行为，这些行为无法一一映射到其他工作区中。

这种区别非常重要，因为 Stoplight 迁移包含两个层面。

第一层是文件层：OpenAPI 规范、Markdown 文档、模型文件、图片和项目结构文件。这也是文档模式最直接发挥作用的地方。

第二层是工作流层：您的团队如何评审 API 变更、发布文档、运行测试、管理 mock、共享报告，以及在后端、前端、QA、产品和合作伙伴团队之间进行协作。这一层不应该被视为导入的副产品。这正是 Apifox 可以将契约连接到 API 生命周期其他阶段的地方。

在已连接 Git 的规范优先项目中，团队可以在 Specs 工作区中编辑文件，然后将更改提交并推送回仓库。在文件支持的项目中，团队可以在连接 Git 之前，在 Apifox 内部编辑并保存规范文件。

实际的分工如下：

职责	推荐数据源
API 契约	OpenAPI / Swagger 文件
项目文件结构	仓库或文件支持的项目树
支持的 Stoplight 风格路径设置	.stoplight.json
支持的文档导航输入	toc.json 和 Markdown 文档
日常 API 协作	Apifox 项目工作区
Mock、测试、报告和团队权限	更广泛的 Apifox 平台工作流

这就是迁移的核心价值：团队可以保留以文件为先的契约模型，同时为更多利益相关者提供围绕该契约的、可用的 API 工作区。

这就是迁移数据与迁移工作流之间的区别。导入文件只是单次迁移契约，而连接规范优先项目则能为团队提供一个围绕该契约的工作区。

已连接 Git 与文件支持的迁移路径

并非所有 Stoplight 团队都处于相同的工作流成熟度阶段。

一些团队已经通过 Git 分支和拉取请求（Pull Request）来审查每一次 API 变更。另一些团队虽然将 API 规范和文档作为文件进行管理，但尚未准备好将外部 Git 服务商纳入首期推广计划中。

Apifox 规范优先模式支持这两种路径。

| 路径 | 适用场景 | 典型工作流 | | --- | --- | --- | | 已连接 Git 的规范优先项目 | 已经在 Git 中管理 OpenAPI 规范的团队。 | 连接仓库、同步分支、编辑文件、提交并推送。 | | 文件支持的规范优先项目 | 希望在连接 Git 之前进行基于文件的 API 设计的团队。 | 在 Apifox 中处理规范文件，保存更改，并首先验证工作流。 |

对于大多数 Stoplight 迁移而言，已连接 Git 的项目是更清晰的长期模型，因为代码仓库依然是契约的唯一事实源。

文件支持的项目适用于：团队想要评估编写体验、清理项目文件，或者在采用更严格的 Git 工作流之前分阶段进行迁移。

推荐的迁移方案

采用分阶段的方案，而不是尝试一次性迁移所有的 API 工作流。

分阶段迁移方案：先迁移 OpenAPI 契约，然后重新连接周边的工作流。

1. 审计 Stoplight 风格的仓库

识别 OpenAPI 文件、.stoplight.json、toc.json、Markdown 文档、数据模型、图片以及任何相关的请求或测试资产。

2. 确定单一真理源（Source of Truth）

确认 Git 中的 OpenAPI 文件是否为契约源。如果另一个工具或集合实际上才是单一真理源，请在迁移前先解决该问题。

3. 创建文档模式项目

如果团队准备好将 Git 作为单一真理源，请选择连接 Git 的项目；如果团队希望先验证文件工作流，请选择基于文件的项目。

4. 审查已迁移的内容

检查模块、文档、数据模型、引用的图片、链接、支持的 toc.json 导航输入、支持的 .stoplight.json 路径设置以及规范验证结果。尽可能修改项目文件本身，而不是手动去修补表面问题。

5. 重建工作流级别的资产

围绕已迁移的 API 契约，重新连接 mock、测试、请求示例、CI 任务、报告、权限以及发布职责。

6. 在新工作流中运行第一次实际变更`

进行一次微小的 OpenAPI 变更，对其进行评审、同步，并在需要时更新文档，然后验证下游的 mock、测试和报告是否符合预期。

如果您的团队已经在 Stoplight 风格的仓库中维护 OpenAPI 文件、Markdown 文档和数据模型，那么 Apifox 的文档模式（Spec-first Mode）可以帮助您在重建完整工作流之前测试迁移路径。

什么时候最适合采用此迁移路径

在以下情况下，该迁移路径非常适合：

1. 您的团队将 OpenAPI 或 Swagger 规范作为文件进行管理；
2. 您的 Stoplight 项目包含 Markdown 文档、数据模型、图片、.stoplight.json 或 toc.json；
3. 您的 API 评审流程已经依赖于 Git 分支或拉取请求（Pull Request）；
4. 您希望 API 文档、mock、测试、报告以及协作能够与契约保持连接；
5. 您希望减少 API 文件与前端、QA、产品、平台或合作伙伴团队所使用的工作空间之间的偏差。

在以下情况下，可能需要更多的规划：

1. 真正的 API 单一真信源（source of truth）是 Postman 或 Bruno 集合，而非 OpenAPI；
2. Stoplight 项目严重依赖自定义发布行为；
3. 文档包含许多外部链接、锚点、生成的页面或未被引用的资产；
4. JSON Schema 数据模型存储在需要手动审核的格式或结构中；
5. 团队希望像素级还原 Stoplight 的导航或文档渲染效果。

FAQ

Apifox 的 Spec-first 模式是 Stoplight 的替代方案吗？

对于希望保持 OpenAPI 项目基于文件管理，同时围绕这些文件添加更广泛的 API 协作、测试、mock、文档、报告和权限管理的团队，它可以作为 Stoplight 的替代方案。

我可以将 OpenAPI 规范保留在 Git 中吗？

可以。在连接了 Git 的 Spec-first 项目中，团队可以将 Git 作为单一真信源，同步分支、编辑文件，并将更改提交回代码仓库。

我需要 Git 才能开始吗？

不需要。当团队希望先处理规范文件，稍后再连接 Git 时，可以使用基于文件的 Spec-first 项目。

.stoplight.json 和 toc.json 会被完全保留吗？

不会。Apifox 将这些文件中受支持的部分作为迁移输入。.stoplight.json 主要用于同步期间的路径发现，包括支持的 OpenAPI、Markdown、JSON Schema 根目录、OpenAPI 包含模式（include patterns）、全局排除（excludes）和 tocPath。toc.json 可以帮助组织受支持的文档（DOCS）内容、OAS/模块链接、选定的规范项链接以及 TOC 引用的数据模型导入。最终的在线文档侧边栏仍受 Apifox 的 DOCS/OAS/MODELS 模型的约束，因此可能无法完全保留 Stoplight 的导航结构和任意跨类型的排序。

Markdown 文档会怎样处理？

Markdown 文档可以引入到 Spec-first 项目的工作流中。当存在 toc.json 时，TOC 中列出的文档可以在支持的范围内保留更多其原有的结构。内部链接、锚点、图片和渲染效果仍需进行审核。

JSON Schema 数据模型会怎样处理？

当 JSON Schema 数据模型被受支持的项目结构（例如 toc.json）明确引用时，可以在受支持的范围内进行迁移。不要假设数据模型目录下的每个 JSON 文件都会自动变成数据模型资源。迁移后请检查数据模型格式、名称、目录和引用。

图片会怎样处理？

Markdown 引用的本地图片可以在受支持的范围内进行导入。不要将 formats.image.rootDir 视为该目录下每个图片文件都将被导入的保证。外部图片、data URI、失效引用和未使用的图片文件应单独进行检查。

迁移后我是否需要运行 lint 或校验？

是的。迁移后，可以在导入的 OpenAPI 文件上运行 Specs 校验。Apifox 支持基于 Spectral 的编辑器校验，并可以读取根目录下的 .spectral.yaml、.spectral.yml、.spectral.json、.spectral.mjs，或者回退到 .stoplight/styleguide.json。请利用校验结果来审查契约和样式问题；不要将校验成功直接视作每个 Stoplight 特有行为都被完整保留的证据。

Bruno 或 Postman 用户应该怎么做？

首先确定 OpenAPI 还是集合（collections）是唯一的单一事实源。以文档模式为核心的迁移主要围绕 OpenAPI 和相关的项目文件展开。而基于集合的请求工作流、环境和测试可能需要单独迁移或重建。

Apifox 是否也支持 mock、测试、CI/CD、报告和协作？

是的。文档模式（Spec-first Mode）将基于文件的 API 契约连接到 Apifox 中，而更广泛的 Apifox 平台可以支持围绕该契约的接口文档、mock、测试场景、使用 Apifox CLI 执行 CI/CD、报告、权限以及团队协作。

结论

Stoplight 迁移并不意味着要放弃基于文件的 API 工作。

代码仓库仍然可以作为单一事实源。OpenAPI 规范、Markdown 文档、引用的图片、目录引用的 JSON Schema 数据模型，以及支持的项目结构文件可以保持便携且可评审。与此同时，围绕这些文件的 API 工作流可以变得更加紧密相连。

Apifox 的文档模式（Spec-first Mode）为 Stoplight 团队提供了一条切实可行的迁移路径：在支持的情况下迁移项目中基于文件的部分，仔细审查 Stoplight 特有的结构，并围绕连接的 API 工作区重建工作流级别的资产。

如果您的团队正在评估 Stoplight 迁移，请先审计您的代码仓库结构，并确定哪些文件定义了 API 契约。然后使用文档模式（Spec-first Mode）将这些文件连接到 Apifox 中的接口文档、mock、测试、报告、权限和协作中。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。