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

在选择生成接口文档的工具时，许可证（License）是决策的重要组成部分。开源生成器意味着你可以阅读代码、自托管输出结果、在项目停滞时进行 fork，并且永远不会遇到席位限制，也不会为你已经发布的功能面临付费墙。对于在每次 CI 构建中运行的任务来说，这一点与输出质量同样重要。

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

我会标注每个工具的具体许可证和自托管方案，因为这正是你阅读开源综述而非普通综述的原因。如果你想了解更广泛的领域，顶级 REST API 接口文档工具综述也涵盖了 GUI 平台。OpenAPI 接口定义/规范是下述所有工具都能读取的格式，因此一份有效的接口定义/规范是你的起点。

预先说明：Apifox 出现在文末，它不是开源项目，而是一个商业化的免费增值平台。我将其作为标注的侧记加入，仅用于开源工具无法满足需求

Redocly CLI 是将接口定义/规范转换为精美、自包含 HTML 参考文档的最快方式。它采用 MIT 许可证并遵循核心开源模式：CLI 及其底层的 Redoc 渲染引擎在 GitHub 上开源，而一些托管门户功能则属于 Redocly 的付费产品。build-docs 命令完全属于开源部分。

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

这会生成一个基于 Redoc 构建的 HTML 文件。你可以本地打开它，将其部署在任何静态托管服务上，或者将其作为发布版本的附件。它不会回传数据，且在包缓存后可以离线运行。

最适合：通过一条命令生成简洁的单页接口参考文档，支持 MIT 授权且可自托管。诚实的局限：输出结果是单页的，因此它更像是一个参考文档而非多页门户，且更丰富的主题定制功能位于付费版中。如果你正在对比不同的渲染引擎，Redocly 的替代方案对比详细说明了开源与付费的分界线。

Widdershins

Widdershins 是一款基于 MIT 许可证的纯转换器。它的全部工作就是读取 OpenAPI 3、Swagger 2 或 AsyncAPI 并输出 Markdown。由于输出的是纯 Markdown，你拥有完全的控制权：可以提交它，在 pull request 中进行差异对比，或者将其集成到你现有的任何静态网站中。

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

它生成的 Markdown 兼容 Slate，这使其能与本文后续列表中的网站生成器完美搭配。有用的参数：--omitHeader 用于移除前置元数据（front-matter），--language_tabs 用于选择代码示例语言。

最适合：将接口定义/规范内容转换为可进行版本控制的 Markdown，且无任何厂商锁定。诚实的局限：你只能得到 Markdown。它没有样式，也没有渲染好的网站，因此 Widdershins 只是流水线的一半；还需要其他工具将 Markdown 转换为页面。

OpenAPI Generator

OpenAPI Generator 采用 Apache 2.0 许可证并由社区驱动，于 2018 年 fork 自 Swagger Codegen。它以生成客户端 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 生态系统，并希望使用生成存根（stubs）的同一个 Apache 2.0 工具来生成文档的团队。局限性：与 OpenAPI Generator 一样基于 Java，且开发进度比社区分支慢。对于大多数新项目，OpenAPI Generator 是更活跃的选择；Swagger Codegen 的优势在于延续性。

带有 OpenAPI 插件的 Docusaurus

如果单页 HTML 无法满足需求，而你想要一个真正的、具有版本控制功能的文档站，Docusaurus 是开源领域的首选。它采用 MIT 许可证，由 Meta 开发，是网络上使用最广泛的静态网站生成器之一。它本身支持渲染 Markdown 和 MDX；而由 Palo Alto Networks 维护的 docusaurus-openapi-docs 插件（同样采用 MIT 协议）则增加了从接口规范到文档的生成功能。

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 文件转换为在 Docusaurus 站点内渲染的 MDX 页面，并配有“立即尝试”面板和侧边栏导航。

优点：适合构建完整的、自托管的文档站，支持版本控制、搜索，并能在生成的参考文档旁添加手写的指南。局限性：这是目前最重的配置方案。你需要搭建一个 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 将其渲染成那种极具辨识度的布局。

最适合：需要对结构和正文拥有编辑控制权的手工编写、叙述性文档，且部署在完全自托管的静态网站上。坦诚地说，它也有局限性：原始仓库已归档（维护者已退出），尽管它仍然可以构建且 fork 版本很活跃，而且 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 或代理中。Apifox CLI 完整指南详细介绍了 auth 和每个命令组。如果你追求的是 Markdown 导出工作流，那么关于支持 Markdown 导出的接口文档生成器部分会有更深入的介绍。

界限在于：开源工具为你提供归你所有的代码、自托管的文件，且没有供应商依赖。Apifox 为你提供从维护项目到可共享文档的一体化路径，代价是它是一个托管的免费增值产品。请根据你的单一事实来源是静态接口定义/规范还是活跃项目来进行选择。

如何选择

根据团队的需求，选择合适的授权协议和输出结果。

简而言之：对于纯粹的接口定义/规范和可共享的 HTML 参考，请使用 Redocly CLI。对于需要进行版本控制的 Markdown，请选择 Widdershins。如果你已经在生成 SDK，OpenAPI Generator 也能处理文档；如果你以 Swagger 为标准，Swagger Codegen 则更适合你。当你需要一个具备版本管理和指南功能的真正门户时，Docusaurus 加上