开源与商业化之间的选择，往往是开发者决策时最纠结的一环。

许可证决定了一切：能不能读源码，能不能自托管，项目停摆后能不能fork，会不会有一天突然被付费墙拦住。

对于要在CI构建中反复跑的任务来说，这些因素甚至比输出质量更值得较真。

这份清单筛出来的，是那些真正可以通过命令行运行的开源接口文档工具。

每个项目都在GitHub上托管，采用MIT或Apache 2.0这样的真许可证。源码可查，无需账号就能免费跑起来。

你只需要把OpenAPI或Swagger文件丢给它，就能拿到Markdown、静态HTML页面，或者一个完全归你所有、由你自托管的文档站。

我会标注清楚每个工具的具体许可证和自托管方案——毕竟，这才是你选择读一篇开源综述而不是普通综述的理由。

至于更广阔的领域，顶级REST API接口文档工具综述里也涵盖了GUI平台。而OpenAPI规范，则是下面所有工具都能读取的通用格式。所以一份有效的接口定义文件，是你出发的起点。

话说回来，文末会提到Apifox。但它不是开源项目，而是一个商业化的免费增值平台。把它放在这里，主要是作为对照参考。万一哪天开源工具确实满足不了需求，至少有个备选方向。

Redocly CLI

如果你的需求很直接——把OpenAPI规范变成一份精美、自包含的HTML参考文档——Redocly CLI是目前最快的方式。

它采用MIT许可证，遵循核心开源模式：CLI及其底层的Redoc渲染引擎在GitHub上开源。而一些托管门户功能则属于Redocly的付费产品。但关键的build-docs命令，完全是开源范畴。

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

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

最适合：需要快速从OpenAPI规范生成漂亮、可分享的HTML单页参考，且对自托管和零厂商锁定有硬性要求。

局限性：定制化程度有限。如果需要深度调整UI风格，可能需要折腾其主题系统。

Widdershins

Widdershins是另一个值得关注的开源选项，它专注于将OpenAPI规范转换为Markdown。采用MIT许可证，核心逻辑非常纯粹：输入你的接口定义文件，输出结构清晰的Markdown文档。

npx widdershins openapi.yaml -o api-docs.md

最适合：当你需要将接口定义内容纳入版本控制，或者作为后续文档站构建的中间素材时。

坦白说，它也有局限：你只能得到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工具来生成文档和stubs的团队。

局限性：同样基于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进行渲染。

# 克隆你的Slate分支并运行 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 
apifox export --project  --format markdown --output ./api-docs.md
apifox export --project  --format html --output ./api-docs.html

一次导出即可将项目转换为Markdown或HTML，无需构建流水线。而apifox doc和apifox docs-site则通过脚本管理文档资源。输出是结构化的JSON，因此可以干净地通过管道传输到CI或袋里中。

如果你追求的是Markdown导出工作流，关于支持Markdown导出的接口文档生成器部分会有更深入的介绍。

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

如何选择

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

简而言之：

• 对于纯粹的接口规范和可共享的HTML参考，请使用Redocly CLI。
• 对于需要进行版本控制的Markdown，请选择Widdershins。
• 如果你已经在生成SDK，OpenAPI Generator也能处理文档。
• 如果你以Swagger为标准，Swagger Codegen则更适合你。
• 当你需要一个具备版本管理和指南功能的真正门户时，Docusaurus加上OpenAPI插件是不二之选。
• 而Slate，则适合那些追求经典三栏布局、且愿意手动编写Markdown的团队。