免费开源的接口文档 CLI 工具

在选择用于生成接口文档的工具时，开源协议是一个关键的考量因素。使用开源的生成器意味着你可以阅读代码、自托管输出结果、在项目停滞时自行 fork，并且永远不会遇到席位限制，或是已上线的功能突然被收费墙拦截的尴尬。对于每次 CI 构建都要运行的任务来说，这一点与输出质量同样重要。

本清单精选了可在命令行中运行的开源接口文档工具。这里的每个工具都提供了源码，且采用了真正的开源协议（MIT 或 Apache 2.0），托管在 GitHub 上，并可完全免费运行，无需注册账号。你只需将其指向 OpenAPI 或 Swagger 文件，它就会为你生成 Markdown、单个静态 HTML 页面，或者一个完全由你拥有并自行托管的完整文档站。

我会标注出每个工具的具体开源协议以及自托管方案，因为这正是你选择阅读这篇开源工具盘点而非普通盘点的原因。如果你想了解更广泛的领域，最受欢迎的 REST API 接口文档工具盘点也涵盖了 GUI 平台。所有以下工具都支持读取 OpenAPI 规范格式，因此一个有效的规范是你的起点。

首先说明一点。Apifox 出现在接近尾部的地方，它并不是一个开源项目，而是一个商业免费增值平台。我将其列入只是作为一个标注说明，以备开源工具无法满足需求时使用，并且我会明确划分这一界限。

什么是真正的“开源” CLI 文档工具

开源并不仅仅是“免费下载”。对于要整合到构建流程中的文档工具，有三点决定了一个工具是否真正属于你：

真实的开源协议。 MIT 或 Apache 2.0 协议意味着你可以不受限制地在商业中免费使用、修改和重新分发该工具。两者均已获得 OSI 批准。Apache 2.0 还额外包含明确的专利授权，这更受一些企业法务团队的青睐。以下列出的每个工具都采用了这两者之一。

可自托管的输出结果。 开源文档的核心在于完全不依赖供应商的服务器。这些工具会生成静态文件：供你提交的 Markdown、单个 HTML 页面，或者包含 HTML/CSS/JS 的目录。你可以将其托管在 GitHub Pages、S3 或普通的 Nginx 服务器上，无论该工具背后的开源项目是否还在维护，它都能继续正常工作。

维护与社区。 只有当代码依然活跃时，源码可用才真正有意义。Star 数量、最近的提交记录和未解决的 Issue 能够告诉你，在需要时进行 fork 是否可行。这里有几个工具虽然已被归档，但依然可以正常使用，届时我会特别说明。

如果你想从免费的角度来对比开源和免费增值方案，可以参考另一篇“免费接口文档工具”的盘点文章。下面，我们进入工具介绍环节。

Redocly CLI

Redocly CLI 是将规范转换为精美、独立的 HTML 参考文档最快的方法。它采用 MIT 许可并采用开放核心（open core）模式：CLI 及其底层的 Redoc 渲染引擎在 GitHub 上开源，而一些托管门户功能则属于 Redocly 的付费产品。其 build-docs 命令完全属于开源部分。

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

这会生成一个基于 Redoc 构建的 HTML 文件。你可以直接在本地打开它，将其部署到任何静态托管服务上，或者作为发布版本的附件。它不会向外发送任何数据，一旦在本地缓存了相关包，你就可以在离线状态下运行它。

最擅长：只需一条命令即可生成干净的单页 API 参考文档，采用 MIT 许可且支持自托管。客观局限：输出结果为单页面，因此它更像是一个参考文档，而不是多页面的门户网站，且更丰富的定制主题功能属于付费级别。如果你正在对比不同的渲染引擎，Redocly 替代方案对比中详细说明了开源与付费的界限。

Widdershins

Widdershins 是一款采用 MIT 许可的纯转换器。它读取 OpenAPI 3、Swagger 2 或 AsyncAPI 并输出 Markdown，这就是它的全部工作。由于输出是纯 Markdown，你拥有它的完全控制权：可以提交它、在 Pull Request 中进行 diff 对比，或者将其导入到你已运行的任何静态网站中。

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

它编写的 Markdown 与 Slate 兼容，这使它能很好地与本文后面 festival 提到的网站生成器配合使用。常用参数：--omitHeader 用于跳过 front-matter 头部信息，而 --language_tabs 用于选择示例代码的语言。

最擅长：将规范内容转换为可进行版本控制的 Markdown，无任何平台锁定。客观局限：你只能得到 Markdown 文件。没有样式，也没有渲染后的网站，因此 Widdershins 只是整个流水线的前半部分，还需要其他工具来将 Markdown 转换为网页。

OpenAPI Generator

OpenAPI Generator 采用 Apache 2.0 许可并由社区运营，于 2018 年从 Swagger Codegen 分叉（fork）而来。它最著名的功能是生成客户端 SDK，但它也附带了文档生成器：markdown 生成器会写入一个 Markdown 目录，而 html2 则会写入一个独立的 HTML 页面。

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/

Apache 2.0 许可及其专利授权使其很容易通过谨慎的法务团队的审批，而且该项目是该领域中最活跃维护的项目之一。

最适合：在具有强大社区支持的宽松开源许可下，复用同一个工具来生成 SDK 和文档。真实局限：npm 包装器在首次运行时仍需下载 Java jar 包，因此它不是单个二进制文件，且模板化输出比较单调。如果你只需要文档，还有更轻量级的转换工具可供选择。

Swagger Codegen

Swagger Codegen 是来自 Swagger 团队的原生模板驱动生成器，采用 Apache 2.0 许可协议。它早于 OpenAPI Generator 分支，目前仍由 SmartBear 维护。对于文档，它提供了两条路径：用于静态单页参考的 html 和用于小型交互式网站的 dynamic-html。

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/

这两个项目同根同源，共享许多选项，因此如果你的团队已经对 Swagger 工具链进行了标准化，使用它能让你保持在相同的生态内。

最适合：已经投入 Swagger 生态、并希望通过生成桩代码的同一个 Apache 2.0 工具来生成文档的团队。真实局限：与 OpenAPI Generator 一样，它也是基于 Java 的，且开发进度慢于社区分支。对于大多数新项目，OpenAPI Generator 是更活跃的选择；而 Swagger Codegen 则胜在延续性。

Docusaurus 搭配 OpenAPI 插件

如果单个 HTML 页面不够用，而你想要一个真正的、支持版本控制的文档网站，Docusaurus 是开源领域的顶梁柱。它采用 MIT 许可协议，由 Meta 开发，是网络上使用最广泛的静态网站生成器之一。它本身只渲染 Markdown 和 MDX；而同样采用 MIT 协议、由 Palo Alto Networks 维护的 docusaurus-openapi-docs 插件，则为其添加了将接口定义/规范转换为文档的功能。

npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

在配置好该插件的接口定义/规范路径后，gen-api-docs 会将 OpenAPI 文件转换为 MDX 页面，并渲染在 Docusaurus 网站中，同时配备“Try it”面板和侧边栏导航。

最适合：需要完整的、自托管的文档门户，且除了自动生成的参考文档外，还需要版本控制、搜索和手写指南的场景。真实局限：这是目前最重的配置。你需要搭建一个 React 网站并配置构建步骤，因此如果只需要一个参考页面，这就显得大材小用了。对于纯参考页面，Redocly CLI 是更便捷的途径。

Slate

Slate 是经典的三栏式接口文档布局：左侧是导航，中间是说明文字，右侧是代码示例，全部渲染为一个静态网站。它采用 Apache 2.0 开源协议，基于 Middleman 构建，因此需要 Ruby 工具链。与上述转换器不同，Slate 不直接读取 OpenAPI；你需要编写 Markdown，然后由 Slate 将其渲染出来。

# after cloning your Slate fork and running bundle install
bundle exec middleman build

这会将一个完整的静态网站写入到 build/ 目录中，你可以将其托管在任何地方。这就是 Widdershins 发挥作用的地方：将你的接口定义/规范转换为 Markdown，然后让 Slate 将其渲染成那种经典的布局。

最适合：在完全自托管的静态网站上，对结构和说明文字有精细编辑需求的手工编写、叙事型接口文档。坦白局限：原仓库已被归档（维护者已退出），尽管它仍可构建且分支（forks）依然活跃，而且 Ruby 依赖项比 npx 一行命令要重得多。如果你的接口文档是直接从接口定义/规范重新生成的，那么使用转换器会更轻量。

Apifox CLI（坦白说，这并非开源选择）

上述工具都是开源的，且各自负责其中一个环节：转换、渲染或托管静态文件。它们遗留的空白是一个处于活跃状态的项目。如果你的 API 不仅仅是一个孤立的 YAML 文件，而是一个包含接口、数据模型和示例的持续维护的项目，你最终不得不手动串联转换器、渲染器和托管服务，并保持这三者同步。

这正是 apifox-cli 二进制文件所填补的空白。坦白说明其许可协议：Apifox 并不是开源的。它是一个有免费额度的商业免费增值平台，其 CLI 与托管的项目通信，而不是与本地接口定义/规范通信。我在此处列出它，只是为了客观对比开源工具所涵盖和未涵盖的内容，而不是将其作为开源选项。

npm install -g apifox-cli
apifox login --with-token <YOUR_TOKEN>
apifox export --project <projectId> --format markdown --output ./api-docs.md
apifox export --project <projectId> --format html --output ./api-docs.html

一次导出即可将项目转换为 Markdown 或 HTML，无需构建流水线，并且 apifox doc 和 apifox docs-site 可以通过脚本管理接口文档资源。输出为结构化的 JSON，因此可以干净地管道输出到 CI 或 Agent。Apifox CLI 完整指南详细介绍了 auth 和各个命令组。如果你追求的是 Markdown 导出的工作流，那么关于具有 Markdown 导出功能的 API 文档生成器文章会进行更深入的探讨。

区别在于：开源工具为你提供自己拥有的代码、自托管的文件，并且没有厂商依赖。而 Apifox 提供了从维护的项目到可共享接口文档的一体化路径，代价是它是一个托管的免费增值产品。请根据你的单一真理源（Source of Truth）是静态的接口定义/规范还是活跃的项目来做出选择。

简而言之：如果只需要一份纯粹的规范和可共享的 HTML 参考文档，请使用 Redocly CLI。如果需要进行版本控制的 Markdown，请使用 Widdershins。如果你已经在生成 SDK，OpenAPI Generator 也能同时生成接口文档；如果你的团队已经标准化使用 Swagger，那么 Swagger Codegen 是理想之选。如果你需要一个支持版本控制和指南的真实门户网站，Docusaurus 配合 OpenAPI 插件是开源方案的中流砥柱，而 Slate 则是手写和编辑控制类文档的首选。这些工具全部开放源码且支持自托管，因此你交付的任何内容都不会依赖于某家供应商是否能持续运营。如果想了解更广泛的免费方案，免费接口文档工具汇总将开源和免费增值选项整理在了一起。

总结

选择开源文档 CLI 工具取决于许可证、输出格式以及文档的托管位置。MIT 和 Apache 2.0 许可证都允许你免费使用、修改和自托管，无需支付席位费。因此，请选择能够满足你输出需求的最小化工具：仅需单页可选择 Redocly CLI；需要 Markdown 可选择 Widdershins；需要在 SDK 旁附带接口文档可选择 OpenAPI Generator 或 Swagger Codegen；需要门户网站可选择 Docusaurus；需要手工编排的页面可选择 Slate。

如果你的 API 存在于一个持续维护的项目中，而不是一个零散的文件里，并且你更希望直接导出接口文档，而不是串联使用三个工具，那么可以下载 Apifox 并尝试针对项目运行 apifox export。它可以轻松集成到 CI 任务中，使得每次 API 变更时文档都会重新构建，不过需要明确的是，它是一个免费增值平台，而不是一个开源的二进制文件。