如何从 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 也发布了其专属的迁移指南以及对应的命令映射。选择这条路线也无可厚非。

而 Apifox 则是为了实现不同的目标。如果你希望规范不仅仅是一个静态文件，就可以迁移到 Apifox CLI。与其验证和打包一个静态文档，不如将整个定义引入到一个动态工作空间中，然后在导入时对其进行校验，在需要时导出合并后的文件，并可选择 mock API、针对其运行测试场景，以及基于同一数据源发布文档。swagger-cli 以前只做两件事，而 Apifox 涵盖了其余的生命周期。

请根据适用性而非炒作来做出选择。如果你想要一个纯终端运行的、轻量级且配置驱动的 linter 和打包器，Redocly 更胜一筹。如果你更希望拥有一个集设计、mock、测试和文档于一体的平台，而不是把好几个工具拼凑在一起，那么 Apifox 胜出。

swagger-cli 与 Apifox CLI 的功能对比

swagger-cli 只有两个命令：

• swagger-cli validate <file> 根据数据模型校验 Swagger 2.0 或 OpenAPI 3.0 文档，并验证其 $ref 指针是否已成功解析。
• swagger-cli bundle <file> 追踪这些 $ref 指针，并将多文件定义合并为一个单文件，支持输出路径 (-o)、类型 (-t json|yaml)、完全解引用 (-r) 和缩进 (-f) 等选项。

这就是该工具的全部功能。它不会根据风格规则进行 lint 检查、生成文档、运行测试或进行任何 mock。

Apifox CLI 将这两个任务映射到它的两个命令上，并在此基础上进行了扩展：

• **apifox import** 将定义导入到 Apifox 项目中，并在导入过程中对其进行校验。多文件规范中的 $ref 指针会被自动解析为统一的资源。这就是您的校验步骤加上导入过程。
• apifox export 从项目中导出一个合并后的单文件，并允许您在导出时选择 OpenAPI 版本。这就是您的合并（bundle）步骤，外加可选的版本升级以及导出 HTML 或 Markdown 文档的能力。
• apifox run 执行测试场景和测试套件，并为 CI 提供 JUnit 和其他报告器。swagger-cli 没有与之等价的功能。
• 资源命令（endpoint（接口）、schema（数据模型）、mock、environment（环境）、branch（迭代分支）等）可在导入规范后直接在终端管理项目。

需要准确指出的一点是：Apifox 在导入时会校验结构，但它不是一个可配置的风格指南 linter。它没有 apifox lint 命令，也不支持自定义规则集。如果您依赖特定的风格 lint 检查，这部分功能将无法迁移，您能获得什么部分将介绍如何处理这种情况。

安装与登录

Apifox CLI 作为一个 npm 包发布。请全局安装它：

npm install -g apifox-cli@latest

然后使用访问令牌进行身份验证：

apifox login --with-token <TOKEN>

您可以通过 Apifox 客户端或 Web 版获取 Token：点击您的头像，转到账户设置，然后转到 API 访问令牌并生成一个。CLI 会将其保存在 ~/.apifox/config.toml 中。请像对待其他机密信息一样对待它，不要将其打印在日志中或提交到您的代码仓库。

如果您想了解每个参数（flag）并进行更深入的探索，Apifox CLI 完整指南和官方 Apifox CLI 文档涵盖了所有内容。对于本次迁移，您只需完成安装和登录即可开始。

命令映射表

以下是 swagger-cli 到 Apifox CLI 的直接转换对应关系。结构上的一个区别是：Apifox 是基于项目运行的，因此大多数工作流是“先导入再导出”，而不是针对单个独立文件执行单个命令。

对迁移最重要的两个单元格是前两行。它们下面的所有内容都是 swagger-cli 从未具备的功能。--oas-version 参数是最显著的升级：swagger-cli 可以打包合并一个 Swagger 2.0 文件，但无法将其转换为 OpenAPI 3.1。而 Apifox 在导出时可以做到这一点，这在重构旧版契约时非常方便。如果你的目标主要是输出文档，将 OpenAPI 导出为 Markdown 会更深入地探讨该格式。

逐步迁移指南

以下是从 swagger-cli 配置转换到 Apifox 工作流的完整路径。

1. 获取你的项目 ID。 在 Apifox 应用中创建或打开一个项目。项目 ID 会显示在项目设置和 URL 中。你需要通过 --project 参数将其传递给每个 CLI 命令。

2. 导入根接口规范。 将 Apifox 指向你定义的入口文件。带有 $ref 指针的多文件规范会自动解析，因此你只需导入根文件，Apifox 就会自动拉取其余部分：

apifox import --project 123456 --format openapi --file ./openapi.yaml

如果接口规范格式错误或 $ref 悬空，导入将会失败。该失败就是你的验证关卡，类似于以前 swagger-cli validate 所做的工作，现在已被合并到导入流程中。

3. 在 App 中验证。 打开项目并确认你的接口、数据模型和 parameter 已正确导入。这种可视化检查在 swagger-cli 中是没有对应功能的，在迁移过程中值得做一次，以确认导入结果符合你的预期。

4. 导出整合后的文件。 当你需要单个扁平文件（用于下游工具、客户端生成器或制品）时，可以将其导出。选择你需要的 OpenAPI 版本：

apifox export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

这取代了 swagger-cli bundle。$ref 指针在导入时就已经被解析，因此导出的文件就是你整合后的单文件输出。

5. 将其接入 CI。 用导入（在摄入时验证）和导出（打包合并）替换旧的 swagger-cli 步骤，如果编写了场景，还可以添加测试运行。下一节将提供一个完整的 GitHub Actions 示例。

使用 GitHub Actions 的 CI 示例

该工作流会安装 CLI，使用来自仓库 secrets 的 Token 进行登录，导入接口规范以进行验证，导出合并后的产物，然后使用 JUnit 报告器运行测试场景，从而使失败的测试导致检查失败并拦截 PR。

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apifox:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apifox CLI
        run: npm install -g apifox-cli@latest

      - name: Log in
        run: apifox login --with-token ${{ secrets.APIFOX_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apifox import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apifox export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apifox run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

将此 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 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋 企业微信

@Apifox 专属顾问

扫码备注: 私有化 + 公司名