Swagger CLI 迁移到 Apifox CLI 指南

如果你的流水线里仍在运行 swagger-cli validate 和 swagger-cli bundle，说明你还在基于一个已经停止维护的工具维持脚本。swagger-cli 的 GitHub 仓库已经明确写明：这个包不再维护。README 也提到，面对庞大的用户规模却几乎没有相应回馈，维护成本过高，因此建议新用户改用其他工具。

因此，现在正是重新评估规范工作流下一步方向的时候。本文定位非常清晰：这是一份迁移操作指南，而不是入门教程。如果你暂时不准备迁移，只想继续使用旧工具，Swagger CLI 指南已经完整说明了 validate 和 bundle 的使用方式。本文只聚焦一个核心问题：如何从 Swagger CLI 平稳迁移到 Apifox CLI，并尽量减少对现有 CI 的影响。

如果你希望结合实际命令进行操作，可以下载 Apifox。它支持免费开始使用，无需信用卡。

为什么建议现在迁移

先说结论：swagger-cli 被弃用且无人维护，已经不是短期现象。虽然它目前仍可运行，很多流水线今天依旧在调用它，但一个无法获得 Bug 修复和规范更新的工具，本质上已经成为构建流程中的技术债务。而且，维护者本人也明确建议用户停止继续依赖它，并尽快寻找替代方案。

官方特别提到过一个替代方向。如果你只需要在终端中完成验证和打包，Redocly CLI 是最接近无缝替换的选择。它是开源、代码优先，并且原生面向终端场景。它的 lint 命令可用于结构验证，redocly bundle 在解析 $ref 指针时，与 swagger-cli bundle 的行为保持一致。如果你的目标只是实现 1:1 替换，并继续将规范保存在仓库中的单文件内，那么 Redocly 确实是一个自然选择。Redocly 也提供了专门的迁移指南和命令映射，因此走这条路线完全合理。

把这个 Token 保存为仓库 secrets 中的 APIFOX_ACCESS_TOKEN，这样它就不会出现在日志里。参数 -r "cli,junit" 会启用报告器并输出 JUnit XML 文件，你的 CI 可以将其作为测试报告展示；如果测试场景失败，则会返回非零退出码，从而阻止合并。想了解更完整的流水线实践，可参考 Apifox CLI 的 CI/CD 指南；如果你使用特定 runner，也可以查看 Apifox CLI 配合 GitHub Actions 的使用教程。

迁移后除了验证和打包，还能得到什么

这正是迁移真正产生价值的部分，也是需要明确说明的重点。

首先是 mock 服务器。接口规范导入项目后，Apifox 可以基于规范直接生成 mock 响应。在后端服务尚未完成之前，前端就可以围绕该 API 提前开发。而 swagger-cli 从未覆盖这类运行时能力。

自动化测试也是一个典型场景。apifox run 可以直接向正在运行的 API 发起真实请求，并根据返回结果执行断言校验。测试场景可先在客户端中以可视化方式配置，再在 CI 环境里通过无头模式执行。这正好补上了 swagger-cli 长期缺失的一环：规范校验通过，只能说明契约格式有效，并不能证明真实实现一定与规范严格一致。

另外还有托管与导出文档。通过 apifox export --format html 或 --format markdown，可以直接基于同一份源文件输出文档，无需额外维护独立的文档构建流程。

不过也需要明确一个限制。Apifox CLI 不提供可配置、代码优先的风格指南 linter，也不支持自定义规则集。虽然导入时会执行结构校验，但你无法通过 CLI 编写 Spectral 或 Redocly 风格的规则，同时也没有 apifox lint 命令。如果你过去依赖严格的 lint 检查，例如统一命名规范、强制描述字段、要求每个响应必须包含示例，那么仍然需要继续使用专业 linter。你可以将 Apifox 与 Spectral 或 Redocly 结合使用，并在 CI 中把它们作为独立步骤运行。OpenAPI linter 设置指南已经说明了这种接入方式。二者并不冲突：用专业工具完成 lint 校验，再由 Apifox 负责 API 生命周期管理。

开发过程中常用的 API 全流程管理工具：Apifox

在以上迁移内容之外，还可以补充介绍一个对开发协作同样重要的工具——Apifox。它集 API 文档、调试、设计、测试、Mock 和自动化测试于一体，是当前常见的研发提效工具之一。

如果你正在进行项目开发，可以体验它相对友好的界面设计。它兼容 Postman 和 Swagger 数据格式，数据导入较为方便，即使是初次接触的用户也能较快上手，点击这里即可注册使用。

此外，除个人和普通团队场景外，对于安全合规要求较高，或需要在内网环境中协作的企业，Apifox 也提供私有化部署方案。