用于 API 设计的免费开源 CLI 工具

API 设计早在任何代码发布之前就已经在你的接口定义/规范文件中开始了。遗忘的风格规则、遗漏的破坏性变更、与上周发布内容产生偏差的数据模型——所有这些在事后修复的成本都要高得多。命令行工具可以在源头捕获这些问题，并且直接在 CI 中自动执行，无需任何人手动操作 UI。

下文会重点介绍该工具链中的开源部分。这里列出的每个工具都以宽松的许可证提供源码，可以免费运行且无席位费用限制，并且支持自托管或锁定到你控制的特定版本。当你的 API 设计保存在 Git 仓库中，且你希望在每台电脑和每条流水线上运行相同的检查时，这一点至关重要。如果你想全面了解这些工具如何协同工作，可以先阅读我们的 API 设计指南，然后再回到这里选择适合你的 CLI 工具。

我们将介绍六个工具，每个工具都配有真实的安装命令和演示其工作原理的单条命令：一个用于风格规则的 linter、一个基于 Go 的快速替代方案、一个同时支持验证的打包工具（bundler）、一个代码和文档生成器，以及两个用于捕获规范版本之间破坏性变更的工具。OpenAPI 规范是它们通用的语言，因此你用一个工具 lint 过的接口规范可以无缝传给下一个工具。

提前说明一点。这里虽然提及了 Apifox，但它不是开源的；它是一款带有免费额度的商业产品，并且不会对你的接口规范进行 lint 校验。因此，它只是作为一个准确的旁注出现，而不是作为开源项目列入。下面介绍的工具才是真正的开源设计工具链。

怎样才算用于 API 设计的开源 CLI 工具

开源有着明确的标准，而不仅仅是一种感觉。对于这份清单，一个工具只有在满足以下三个条件时才算符合条件。

第一，许可证。它必须是你可以阅读的真实的宽松（permissive）或传染型（copyleft）许可证；MIT 和 Apache-2.0 是你在此处最常看到的两种。正是这一点允许你在商业项目中免费使用该工具，且无席位限制。

第二，自托管和版本控制。你可以直接在项目中保存其二进制文件（vendor）、锁定确切的版本，并在物理隔离的 CI runner 中完全离线运行。这里的工具都不会“打电话回家”（即向后台发送数据），也不需要注册账号来执行其核心功能。

第三，维护和社区。仓库有最近的 commit、开放的 issue 能得到解答，并且有公开的变更日志。一个被遗弃的项目即使仍使用 MIT 许可证，也可能不是一个好的选择，因此我会在关键地方标注其维护状态。

下面的每一个工具都对照这三点进行了检查。如果某个项目目前处于维护缓慢的状态，我会明确指出。

Spectral：灵活的 OpenAPI 风格 linter

Stoplight 的 Spectral 是 API 描述领域标杆级的开源 linter，采用 Apache-2.0 协议授权。它通过读取规则集（包含规则列表的 YAML、JSON 或 JavaScript 文件），并将其应用于 OpenAPI 3.x、OpenAPI 2.0、AsyncAPI 和 Arazzo 文档。如果你的团队制定了书面的 API 风格指南，Spectral 就能帮你将其转化为可执行的规则。

npm install -g @stoplight/spectral-clispectral lint openapi.yaml

它开箱即用，内置了 oas 规则集，可以标记缺失的描述、无效的示例以及结构性问题。但其真正的价值体现在自定义规则上：例如要求每个操作都必须有 operationId、在错误响应中共享数据模型、路径遵循特定的命名规范等。这些规则保存在你的代码仓库中，对每个贡献者而言运行结果完全一致。

最擅长：以代码形式强制执行团队的风格指南。真实局限：Spectral 只能检查单个接口规范，无法对比两个版本，因此需要配合 diff 工具来捕获破坏性变更。

vacuum：最快的 linter，可直接替代 Spectral 规则集

如果说 Spectral 是行业标准，那么 vacuum 就是极致的速度追求者。它是一款基于 Go 语言编写、采用 MIT 协议授权的 linter，100% 兼容 Spectral 规则集。这意味着你可以直接将它指向你已编写的相同规则集，并在大型接口规范上以快得多的速度获取结果。这正是你在 pre-commit 钩子或紧凑的 CI 循环中所期望的。

brew install --cask daveshanley/vacuum/vacuumvacuum lint -d openapi.yaml

-d 参数会为你提供每个规则的详细输出。vacuum 的功能不仅限于 lint，它还能根据相同的接口规范生成 HTML 报告和文档。由于它是一个没有 Node 运行时的单文件编译二进制程序，因此启动速度极快，可以非常干净地部署到容器中。

最擅长：使用现有的规则集快速对大型接口规范进行 lint。真实局限：规则集生态和文档仍然以 Spectral 为中心，因此你通常需要针对 Spectral 的模型编写规则，然后通过 vacuum 运行。虽然这也是其一大特性，但这意味着 Spectral 仍然是你需要首要学习的内容。

Redocly CLI：集 lint 与打包（bundle）于一体的二进制工具

Redocly CLI 采用 MIT 协议授权，涵盖了略有不同的工作场景。它不仅可以进行 lint，其主打功能还在于 bundle：它能将分散在多个 $ref 文件中的接口规范（这是保持大型 API 设计可维护性的明智做法）合并扁平化为一个单文档，以便提供给需要单一文件的工具使用。它还能根据打包后的结果生成 API 参考文档。

npm install -g @redocly/cliredocly lint openapi.yamlredocly bundle openapi.yaml -o dist/openapi.yaml

将接口规范拆分为按资源划分的文件，可以保持 diff 的可读性并减少合并冲突，这是 Git 原生 API 设计工作流的核心。Redocly 的 bundle 步骤能将这些多文件源重新合并为单个产物，以供你的 CI、mock 服务端或文档站使用。

最适合：需要打包和验证步骤的多文件接口规范项目。真实局限：其默认的 lint 规则比完整的自定义 Spectral 规则集更轻量，因此许多团队使用 Redocly 进行打包，并结合 Spectral 或 vacuum 进行深度风格校验。

openapi-generator：将设计转化为客户端、桩代码和文档

直到其他人可以基于它进行构建，设计才算真正完成。openapi-generator 采用 Apache-2.0 协议，支持从 OpenAPI 接口规范生成数十种语言的客户端 SDK、服务端桩代码和文档。将接口规范视为唯一事实源并生成其余内容，是“数据模型优先”和“契约驱动”方法的核心，我们在 API 设计原则中对此进行了介绍。

npm install -g @openapitools/openapi-generator-cliopenapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

可以将 -g typescript-axios 替换为 go、python、java、kotlin 或任何其他支持的生成器。在 CI 中针对每次接口规范变更运行它，您的客户端库就永远不会偏离契约。

最适合：保持生成的代码和文档与设计步调一致。真实局限：它需要 JDK 才能运行（JDK 11+），生成的代码只是一个起点，您通常需要对其进行自定义，且生成器的质量因目标语言而异。在发布之前，请务必检查输出结果。

oasdiff：在影响客户端之前捕获破坏性变更

Linter 只能告诉你单个接口规范是否整洁。它无法告诉你重命名某个字段会破坏生产环境中的所有客户端。oasdiff 是一个采用 Apache-2.0 协议的 Go 语言工具，填补了这一空白：给它两个版本的接口规范，它就会报告它们之间的差异，特别是破坏性变更。

go install github.com/oasdiff/oasdiff@latestoasdiff breaking old-openapi.yaml new-openapi.yaml

breaking 命令仅展示破坏现有调用方的变更；changelog 提供一份人类可读的列表，列出所有发生的变化（无论是否具有破坏性）；diff 则输出完整的机器可读差异。将 oasdiff breaking 集成到 PR 检查中，破坏性变更就会导致构建失败，而不是变成凌晨三点的报警电话。

最适合：在 CI 中拦截破坏性变更。真实局限：它只比较接口规范，因此其效果完全取决于您是否能严格保持接口规范与实际 API 的同步。它不会校验风格，请将其与 Spectral 或 vacuum 配合使用。

Optic：同时进行差异对比与校验，但有维护方面的注意事项

Optic 采用 MIT 协议，它将其他工具拆分的功能合二为一：它在同一个工具中对 OpenAPI 进行校验和差异对比，通过比较两个版本来标记破坏性变更，同时应用风格规则。它甚至可以根据观察到的测试流量生成接口规范。

npm install -g @useoptic/opticoptic diff old-openapi.yaml new-openapi.yaml --check

这是开源清单应当对您坦率说明的：Optic 的公共仓库已于 2026 年初被归档，该项目不再积极维护。MIT 源码仍可运行，因此您可以将其引入自己的代码库自行维护，但您将无法获得新的规则或安全补丁。对于如今的破坏性变更检测，oasdiff 是目前仍在维护的选择；Optic 留在清单中是因为您在现有的流水线中仍然会遇到它。

最适合：已在此投入的团队，或希望在单个 CLI 中完成 lint 和 diff 的开发者。坦诚的局限：自 2026 年初起已停止维护；应视其为遗留软件并规划迁移路径。

Apifox 的定位（以及它不适用的场景）

Apifox 不是开源软件，它不会对您的 OpenAPI 进行 lint 检查，也不强制执行样式规则；Spectral、vacuum 和 Redocly 才是您的 linter，仅此而已。Apifox 提供的是一种不同的权衡方案：它无需您将六个不同的二进制文件拼接在一起，而是通过其免费版加上 apifox-cli 二进制文件，为您提供了一个集成的平台来设计接口和数据模型，然后将结果导出为 OpenAPI，以便直接送回这些开源检查工具中。

npm install -g apifox-cli apifox login --with-tokenapifox endpoint list apifox export --format openapi -o openapi.yaml

该 CLI 拥有针对 endpoint、schema、mock 以及 import/export 的命令组，因此您可以在终端中对 API 设计编写脚本，并将导出的规范交给 openapi-generator 或 oasdiff。请参阅完整的 Apifox CLI 指南以获取完整的命令集。坦率地讲：Apifox 是一个与开源工具链配合良好的商业化、集成式选项，它不是 linter 的替代品，本身也不是开源项目。

如何选择

根据任务选择工具。大多数团队会同时运行两到三个工具，而不是仅用一个。

一个实用的工具链组合：使用 Spectral 或 vacuum 进行风格校验，使用 Redocly 进行打包，使用 oasdiff 识别破坏性变更，以及使用 openapi-generator 生成客户端。如果维护这么多工具超出了你的精力范围，一体化平台可以在一个地方搞定设计与导出的工作。想要了解 CLI 之外更广泛的工具生态，请参阅我们的 Swagger 替代方案（用于 API 设计和测试）指南，以及如何设计 REST API 的基础知识。

总结

用于 API 设计的开源 CLI 工具链已经非常成熟且可以免费使用：Spectral 和 vacuum 进行校验，Redocly 进行打包，openapi-generator 生成客户端，oasdiff 防范破坏性变更，同时 Optic 也是一个值得了解的备选遗留方案。将它们接入 CI，你的 API 契约就会在每次推送时自动接受检查，且无需支付按席位计费的费用，也无需担心厂商锁定。

如果你更倾向于在一个集成工具中设计接口和数据模型，并将干净的 OpenAPI 导出到相同的流水线中，请下载 Apifox 并尝试 apifox-cli；它是开源技术栈的商业伴侣，而不是 linter 的替代品。无论采用哪种方式，目标都是相同的：在终端中、在设计缺陷触达用户之前，就将其捕获。

开发必备：API 全流程管理神器 Apifox

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

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

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