如何从 Swagger CLI 迁移到 Apifox CLI

如果你仍在流水线中运行 swagger-cli validate 和 swagger-cli bundle，这意味着你正在围绕一个无人维护的工具来维护脚本。swagger-cli GitHub 仓库现在已经直接说明了这一点：该包已不再维护。其 README 中提到，维护一个庞大的用户群但几乎得不到回馈负担过重，因此建议新用户选择其他工具。

因此，现在是决定你的规范工作流下一步该去向何处的好时机。本指南是一份迁移操作手册，而非使用教程。如果你还没准备好迁移，只是想继续使用旧工具，Swagger CLI 指南详细介绍了 validate 和 bundle 的用法。而本文则是关于如何离开，具体介绍如何在不破坏 CI 的情况下，将 Swagger CLI 迁移到 Apifox CLI。

如果你想跟随实际命令进行操作，可以下载 Apifox。它可以免费开始使用，无需信用卡。

为什么现在迁移

首先说句实话：swagger-cli 已经被弃用且无人维护有一段时间了。它目前仍能运行，许多流水线今天依然在调用它。但是，一个无法获得 Bug 修复或规范更新的工具，对你的构建而言就是技术债务，而且维护者自己也建议弃用它并寻找替代方案。

他们特别推荐了一个继承者。如果你只需要在终端中进行验证和打包，Redocly CLI 是最接近的无缝替代方案。它是开源、代码优先且原生支持终端的。它的 lint 命令用于执行结构验证，而 redocly bundle 解析 $ref 指针的方式与 swagger-cli bundle 完全一致。如果你的唯一目标是进行 1:1 替换，并将规范保留为仓库中的单文件，那么 Redocly 是很自然的选择。Redocly 也发布了其专属的迁移指南以及对应的命令映射。选择这条路线也无可厚非。

将此 Token 作为 APIFOX_ACCESS_TOKEN 存储在你的仓库 secrets 中，这样它就永远不会出现在日志中。其中 -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 中以无头（headless）模式运行它们。这弥补了 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 全流程管理神器 Apifox

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

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

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