如果你还在 CI/CD 流水线中执行 swagger-cli validate 和 swagger-cli bundle，其实意味着你的脚本体系仍然依赖一个已停止维护的工具。swagger-cli 的 GitHub 仓库已经明确说明：这个包不再持续维护。其 README 也提到，面对庞大用户群却几乎收不到有效回馈，维护成本过高，因此官方建议新用户优先选择其他替代工具。
因此，现在正是重新评估 OpenAPI / Swagger 规范工作流的合适时机：你的下一步迁移方向应该是什么。这篇指南的目标非常清晰，它是一份面向实际落地的迁移手册，而不是基础入门教程。如果你暂时不准备迁移，只想继续使用旧工具，那么 Swagger CLI 指南已经对 validate 和 bundle 的使用方式做了详细说明。而本文只聚焦一个核心问题：如何从 Swagger CLI 平稳迁移到 Apifox CLI，并尽量不影响现有 CI 流程。
如果你希望跟着实际命令一步步操作，可以下载 Apifox。它支持免费开始使用，无需绑定信用卡。
为什么现在迁移
先说结论：swagger-cli 被弃用且无人维护，已经不是最近才发生的事。虽然它现在仍然可以运行，很多自动化流水线今天也还在继续调用它，但一个无法获得 Bug 修复、功能更新或规范兼容支持的工具，对构建流程来说就是持续累积的技术债务。而且连维护者本人也已经明确建议用户停止依赖它，并尽快寻找替代方案。
官方其实也给出了比较明确的继任方向。如果你只需要在命令行里完成 API 规范校验和打包，Redocly CLI 是最接近原有体验的替代工具。它是开源的、偏代码优先的，并且天然适合终端环境。它的 lint 命令可用于结构校验，而 redocly bundle 在解析 $ref 引用时，与 swagger-cli bundle 的行为基本一致。如果你的目标只是做 1:1 命令替换，并继续把 OpenAPI 规范维护为仓库中的单文件，那么 Redocly 确实是一个很自然的选择。Redocly 也提供了自己的迁移文档和命令映射关系，因此走这条路线完全合理。
将这个 Token 以 APIFOX_ACCESS_TOKEN 的形式保存到仓库 secrets 中，这样它就不会暴露在日志里。其中 -r "cli,junit" 报告器会输出一个 JUnit XML 文件，方便你的 CI 系统将结果展示为测试报告；如果测试场景执行失败，也会返回非零退出码，从而阻止代码合并。想了解更完整的流水线实践，可以查阅 Apifox CLI CI/CD 指南；如果你使用的是特定 runner，例如 GitHub Actions，也可以参考 Apifox CLI 配合 GitHub Actions 的实战教程。
除了验证和打包，你还能获得什么
这正是迁移真正开始体现价值的地方，也是最值得直说的部分。
首先是 mock 服务器。当你的 API 接口规范导入项目后，Apifox 可以直接基于规范生成 mock 响应。在后端服务尚未完成开发之前，前端团队就能提前围绕该 API 开展联调与页面开发。而这一类运行时能力，swagger-cli 从来没有覆盖过。
自动化测试也是一个非常关键的应用场景。apifox run 可以直接对真实运行中的 API 发起请求，并根据返回结果执行断言校验。测试场景可以先在客户端中通过可视化方式设计完成，进入 CI 环境后，再通过无头（headless）模式自动运行。这样就补齐了 swagger-cli 长期缺失的一环：接口规范校验通过，只能证明契约格式合法，但并不能证明线上或测试环境中的真实实现一定严格符合 OpenAPI 规范。
还有托管与导出文档的能力。通过 apifox export --format html 或 --format markdown，你可以直接基于同一份 API 源数据生成 HTML 文档或 Markdown 文档，而不需要额外维护单独的文档构建流程。
当然，也需要客观看待它的边界。Apifox CLI 目前并不提供可配置、代码优先的风格指南 linter，也不支持自定义规则集。虽然它在导入 API 定义时会执行基础结构校验，但你无法像使用 Spectral 或 Redocly 那样，通过 CLI 编写和执行自定义规则，也没有 apifox lint 这样的命令。如果你原来的工作流高度依赖严格 lint 检查，例如统一命名规范、强制描述字段必填、要求每个响应都提供示例，那么仍然建议保留专门的 API lint 工具。最佳做法是将 Apifox 与 Spectral 或 Redocly 组合使用，在 CI 中拆分为独立步骤执行。OpenAPI linter 配置指南中也介绍了这种接入方式。两者并不冲突：用专业 linter 完成规范治理，再用 Apifox 管理 API 生命周期。
开发必备：API 全流程管理神器 Apifox
在介绍完以上迁移思路后，也值得额外提一下另一个对开发团队非常有价值的效率工具 —— Apifox。作为一款集 API 文档、接口调试、API 设计、测试、Mock、自动化测试于一体的工具，Apifox 已成为很多团队提升研发协作效率与接口管理效率的重要选择。
如果你正在进行项目开发，不妨体验一下 Apifox 友好的产品界面。它完整兼容 Postman 与 Swagger / OpenAPI 数据格式，数据导入过程非常便捷，即使是刚接触 API 管理工具的新手，也能快速上手使用，点击这里即可注册体验。
值得一提的是，除了适合个人开发者和常规团队协作外，对于有更高安全合规要求，或需要在内网环境中进行协同研发的企业，Apifox 还提供可深度定制的私有化部署方案。
