从 Stoplight 迁移到 Apifox，绝不只是导入一个 OpenAPI 文件这么简单，而是要整体迁移一套基于文件的 API 设计与协作工作流。

对很多团队而言，Stoplight 项目承载的内容远不止接口定义：其中通常还包括 Git 仓库中的 OpenAPI 规范、Markdown 文档、JSON Schema 数据模型、本地图片资源、用于导航的 toc.json 配置，以及用于路径设置的 .stoplight.json 文件。

不少团队还会在 Postman 中保留请求示例，并在 CI 流程中维护测试脚本。如果从 Stoplight 迁移到 Apifox 时只导入单个 OpenAPI 文件，虽然接口清单能够保留下来，但完整的 API 工作流和上下文往往会丢失。

Apifox Spec-first 模式能够帮助团队在 Stoplight 迁移过程中，将 OpenAPI 文件继续作为单一可信源，同时把这些规范文件连接到更完整的 API 工作空间中，用于接口文档、Mock、测试、报告、权限控制和团队协作。

本指南将帮助你梳理 Stoplight 迁移到 Apifox 的规划思路：哪些内容可以保留、哪些部分需要评估、哪些资产需要重建，以及如何围绕 OpenAPI 契约完成整体连接。

如需查看具体配置与操作步骤，请参考 Spec-first 模式帮助指南。

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

OpenAPI 文件描述的是 API 契约本身，而 Stoplight 风格的项目通常还包含围绕这份契约构建的大量上下文信息。

常见的项目资产包括：

• OpenAPI 或 Swagger 文件，通常存放在 reference 或其他已配置目录中；
• Markdown 文档，通常位于 docs 目录；
• JSON Schema 数据模型文件，通常保存在 models 目录；
• 文档中引用的本地图片资源；
• 用于支持路径配置的 .stoplight.json；
• 用于支持文档导航输入、分组和排序的 toc.json；
• Stoplight 标识信息，例如 x-stoplight-id 或 x-stoplight.id。

如果迁移时只导入一个 OpenAPI 文件，那么虽然接口定义被迁移了，但项目结构与上下文模型仍可能丢失。文档往往需要重新整理，导航结构也可能与原项目不一致，数据模型与文档之间的关联可能被打断。与此同时，测试、Mock 和请求示例可能仍分散在其他独立工具中。

因此，更合理的 Stoplight 迁移方案，应该从代码仓库或文件目录结构入手，而不是只围绕某一个规范文件进行导入。

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

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

最稳妥的迁移策略并不是“全部照搬”。Stoplight 项目中往往会包含一些该平台特有的行为或功能，这些内容并不一定能一一映射到其他 API 平台或工作区中。

理解这一区别非常关键，因为 Stoplight 迁移实际上包含两个层面。

第一层是文件层：包括 OpenAPI 规范、Markdown 文档、模型文件、图片资源以及项目结构文件。这也是文档模式最容易直接发挥作用的部分。

第二层是工作流层：也就是团队如何评审 API 变更、如何发布接口文档、如何执行自动化测试、如何管理 Mock、如何共享测试报告，以及后端、前端、QA、产品和合作伙伴团队之间如何协作。这一层绝不能被视为“导入后自然形成的副产物”。真正决定迁移价值的，恰恰是这一层：Apifox 能把 API 契约与整个 API 生命周期中的关键环节真正打通并连接起来。

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

实际的职责划分如下：

这正是迁移的核心价值所在：团队既能保留“以文件为中心”的 API 契约模型，又能为更多角色提供围绕契约协同工作的可用 API 工作区。

这也体现了“迁移数据”和“迁移工作流”之间的本质区别。导入文件只是一次性迁移契约，而连接规范优先项目，则是在为团队建立一个围绕该契约长期运行的 API 工作空间。

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

并不是所有 Stoplight 团队都处在相同的 API 工作流成熟阶段。

有些团队已经通过 Git 分支与 Pull Request 来审查每一次 API 变更；也有些团队虽然已经使用文件管理 API 规范和文档，但暂时还没有准备好在首轮迁移中接入外部 Git 服务。

Apifox 规范优先模式同时支持这两种迁移路径。

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

对于大多数 Stoplight 迁移场景而言，已连接 Git 的项目通常是更清晰、也更适合长期演进的模式，因为代码仓库仍然是 API 契约的唯一事实来源。

而文件支持的项目更适合以下场景：团队希望先评估编写体验、整理项目文件，或者在正式采用更严格的 Git 工作流之前，以分阶段方式推进迁移。

推荐的迁移方案

建议采用分阶段迁移，而不是试图一次性迁移全部 API 工作流。

推荐的分阶段方案是：先迁移 OpenAPI 契约，再逐步重建和连接周边工作流。

1. 审计 Stoplight 风格的仓库

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

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

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

3. 创建文档模式项目

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

4. 审查已迁移的内容

重点检查模块、文档、数据模型、引用图片、内部链接、支持的 toc.json 导航输入、支持的 .stoplight.json 路径设置，以及规范校验结果。应尽量通过修改项目文件本身来解决问题，而不是只在表面做手工修补。

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

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

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

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

如果你的团队已经在 Stoplight 风格的仓库中维护 OpenAPI 文件、Markdown 文档与数据模型，那么 Apifox 的文档模式（Spec-first Mode）可以帮助你在全面重建工作流之前，先验证整条迁移路径是否可行。

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

在以下情况下，这条 Stoplight 到 Apifox 的迁移路径通常非常适合：

• 你的团队通过文件方式管理 OpenAPI 或 Swagger 规范；
• 你的 Stoplight 项目中包含 Markdown 文档、数据模型、图片、.stoplight.json 或 toc.json；
• 你的 API 评审流程已经依赖 Git 分支或 Pull Request；
• 你希望 API 文档、Mock、测试、报告和协作流程都与契约保持联动；
• 你希望减少 API 文件与前端、QA、产品、平台或合作伙伴团队所使用工作空间之间的偏差。

而在以下情况下，迁移前通常需要更充分的规划：

• 真正的 API 单一真信源（source of truth）是 Postman 或 Bruno 集合，而不是 OpenAPI；
• Stoplight 项目高度依赖自定义发布行为；
• 文档中存在大量外部链接、锚点、生成页面或未被引用的资产；
• JSON Schema 数据模型存储在需要人工审核的格式或结构中；
• 团队希望像素级复刻 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 已成为提升研发效率和规范 API 管理的热门选择。

如果你正在进行项目开发，不妨体验一下它友好的界面设计。Apifox 完全兼容 Postman 和 Swagger 数据格式，数据导入非常便捷，，即使是初学者也能快速上手，点击这里即可注册使用。

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