你有一个 OpenAPI 文件，并希望从中生成文档。你不想搭建服务、登录门户，也不想添加一个会拉取半个 npm 库的构建步骤。你只需要一个命令，读取规范并交付一个 Markdown 文件或一个可以托管在任何地方的单 HTML 页面。
这就是本列表的意义所在。这里的每个工具都很小巧：一个单一的二进制文件、一行 npx 命令，或者一个安装一次即可忘掉的包。它们启动迅速，几乎不需要配置，在完成文档工作的同时不会拖累整个平台。有些会生成 Markdown，你可以直接放入现有的文档站。有些则生成独立的 HTML 文件。所有这些工具都可以在 CI 和终端中运行，而这正是重点。
如果你想了解更广泛的文档平台领域，最佳 REST API 接口文档工具综述涵盖了偏重 GUI 的工具。本文则是针对终端优先、低占用的精选。关于文档生成器读取内容的官方参考，OpenAPI Specification 是下面每个工具解析的事实标准。
什么才算“轻量级”的 API 接口文档 CLI 工具
轻量级并不意味着功能薄弱，而是关于占用空间和摩擦力。由以下四点决定：
安装大小和依赖。 一个二进制文件或一个 npm 包优于一个框架。如果生成一个文档页面意味着要安装语言运行时、打包工具和插件系统，那么无论输出结果如何，它都不算轻量级。
启动和配置。 其中最优秀的工具可以读取你的规范并在零配置下生成输出。你只需将命令指向 openapi.yaml 就能得到一个文件。任何在运行前需要配置文件的工具都会在此失分。
单一用途的输出。 下面的每个工具只做一件事：输入规范，输出文档。Markdown 或 HTML，没有其他多余的东西。这保证了它们在流水线中的快速和可预测性。
随处运行。 没有 GUI，开源工具无需登录，无需维持服务器运行。它在你的笔记本电脑上工作，在 CI 任务中的工作方式也完全相同。对于更广泛的免费选项，免费 API 接口文档工具列表列出了相关平台；而这里是其中的 CLI 部分。
下面开始介绍工具，从体积最小的开始。
Widdershins
Widdershins 几乎是这类工具中最小巧的。它是一个单一的 npm 包，可将 OpenAPI 3、Swagger 2 或 AsyncAPI 文件转换为 Markdown。这就是它的全部工作。它不渲染网站，也不运行服务器；它只交给你一个 .md 文件，然后功成身退。
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
它生成的 Markdown 与 Slate 兼容，如果你计划稍后将其导入静态网站，这一点非常重要。有用的 flag：--omitHeader 会去掉 YAML front-matter，--language_tabs 则控制显示哪些代码示例语言。
擅长：将接口定义/规范内容转换为 Markdown，方便提交、对比差异并放入任何文档系统。局限性：只能生成 Markdown。没有样式，没有交互式的“试一试”面板，也没有托管输出。Widdershins 是一个转换器，而不是渲染器，因此你需要配合其他工具将 Markdown 转换为网站。
OpenAPI Generator (文档生成器)
OpenAPI Generator 最为人熟知的是生成客户端 SDK，但它也提供文档生成器，在只有接口定义/规范时非常方便。markdown 生成器会生成一个 Markdown 目录；html2 生成器则生成一个独立的 HTML 页面。你可以通过 npm 封装器运行它，而无需自行安装 Java。
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/
npm 封装器在底层仍会下载一个基于 JDK 的 jar 包，因此首次运行比 Widdershins 更重。之后只需一条命令即可生成。
擅长：复用可能已用于 SDK 的工具来生成文档，并可在 Markdown 和独立 HTML 之间进行选择。局限性：输出内容较为朴素且由模板驱动，且首次调用会拉取 jar 包，因此并非真正的单二进制文件。如果你只需要文档，还有更轻量级的选择。
Redocly CLI (build-docs)
如果你想通过一条命令获得美观且独立的 HTML 页面，Redocly CLI 是最快的途径。build-docs 命令会将你的接口定义/规范打包成一个基于 Redoc 的独立 HTML 文件。无需服务端，无需单独的托管构建；你得到的文件可以直接打开、通过邮件发送或放在任何静态托管平台上。
npx @redocly/cli build-docs openapi.yaml
默认情况下它会生成 redoc-static.html。可以使用 --output 修改文件名：
npx @redocly/cli build-docs openapi.yaml --output api.html
因为它通过 npx 运行，你甚至不需要全局安装即可尝试。擅长：通过一条命令生成精美的单页参考文档，拥有整洁的默认主题，且无需管理托管事宜。局限性：输出是一个 HTML 文件，因此它更像是一个参考页面，而不是多页面的文档门户，且更丰富的主题和预览功能属于 Redocly 的付费层级。如果你正在将其与其他类似的渲染器进行对比，Redocly 替代方案和 Scalar 替代方案的对比分析了各自的优劣。
Slate
Slate 在这里是个异类：它不是一个接口定义/规范到文档的转换器，而是一个用于手写接口文档的静态网站生成器。你编写 Markdown，Slate 会将经典的三栏式文档布局（导航、内容和代码示例并排显示）构建为一个独立的静态网站。它由 Middleman 驱动，因此需要 Ruby 环境。
# after cloning the slate repo and installing dependencies
bundle exec middleman build
这会将一个完整的静态网站写入 `build/` 目录，你可以将其托管在任何地方。这正是 Widdershins 大显身手的地方：从你的规范中生成 Markdown，然后让 Slate 对其进行渲染，你就能在 Slate 的布局中获得由规范驱动的内容。
**最适合：** 需要对结构和正文进行编辑控制的手工编写、叙述性接口文档。**坦诚地说，它也有局限性：** 它是此列表中最“重”的选项，因为它需要 Ruby 工具链，且自身无法直接读取 OpenAPI；你需要为其提供 Markdown。如果你的文档是直接从规范生成的且很少进行手动编辑，那么单纯使用转换器会更轻量。
## Apifox CLI (导出 + 文档)
上述开源工具各司其职：转换、渲染或托管。如果你的 API 已经存在于项目（project）中，而不是单个 YAML 文件，那么将它们整合在一起的过程往往充满摩擦。这就是 `apifox-cli` 二进制文件的用武之地。它是 [Apifox](https://apifox.com/?ref=apifox.com) 的命令行伴侣，只需一次导出即可将项目转换为 Markdown 或 HTML，无需构建流水线。
通过 npm 安装并使用 Token 进行身份验证：
bash npm install -g apifox-cli apifox login --with-token
然后通过一条命令将项目的接口文档导出为 Markdown 或 HTML：
bash apifox export --project--format markdown --output ./api-docs.md apifox export --project--format html --output ./api-docs.html
该 CLI 还能直接管理文档资源。`apifox doc` 处理项目的 Markdown 文档，而 `apifox docs-site` 则管理已发布的文档站，因此你可以通过脚本或 CI 任务列出、创建和更新文档：
bash apifox doc list --projectapifox docs-site list --project```
输出结果是结构化的 JSON，这使得它很容易通过管道传输到其他步骤或交给代理（agent）处理。关于完整的命令范围，Apifox CLI 完整指南详细介绍了身份验证、项目以及每个命令组的使用。
这里有一个客观的设定。Apifox 不是开源的，也不是一个单一用途的二进制文件；它是一个免费增值平台，CLI 与托管的项目进行通信。它也不会对你的 OpenAPI 进行 Lint 检查或强制执行风格指南；Redocly 和 Spectral 负责这些工作。该 CLI 为你提供的是一条从维护中的 API 项目到可共享 Markdown 或 HTML 的集成路径，而不是手动串联转换器、渲染器和托管服务。如果你特别想要 Markdown 导出路径，关于支持 Markdown 导出的 API 文档生成器部分会对该工作流进行更深入的探讨。
如何选择
根据你的输入形式和所需的输出结果来匹配工具。
| 工具 | 适用场景 | 安装 | 是否开源？ | 输出形式 |
|---|---|---|---|---|
| Widdershins | 规范转 Markdown，速度快 | npm i -g widdershins |
是 (MIT) | Markdown |
| OpenAPI Generator | 与 SDK 并行的文档 | npm i -g @openapitools/openapi-generator-cli |
是 (Apache 2.0) | Markdown 或 HTML |
| Redocly CLI | 单个精美的 HTML 页面 | npx @redocly/cli |
是 (MIT, open core) | 独立 HTML |
| Slate | 手工编写的文档站 | Ruby + Bundler | 是 (Apache 2.0) | 静态网站 |
| Apifox CLI | 从活跃项目导出 | npm i -g apifox-cli |
否 | Markdown, HTML, JSON |
简而言之：如果你只有纯粹的接口定义/规范并希望得到用于提交的 Markdown，请使用 Widdershins。如果你需要一个可共享的 HTML 页面，redocly build-docs 是最快的方法。如果你是手动编写文档并希望有合适的布局，请选择 Slate。如果你的 API 已经存在于某个项目中，并且你希望在一个 CLI 中同时实现导出和文档管理，那么 Apifox 是不二之选。如需了解全面的免费方案，可以参考这篇免费接口文档工具汇总。
总结
轻量级文档工具的选择遵循一个原则：选择能满足你输出需求的最简工具。Widdershins 和 redocly build-docs 只需一条命令就能涵盖大多数“从规范到文档”的场景。当你已经在生成 SDK 时，OpenAPI Generator 非常值得一用。只有在手写文档时，Slate 较大的体量才显得物有所值。而当你的 API 存在于实际项目而非零散的文件中时，apifox-cli 的导出功能可以让你无需构建流水线即可获得 Markdown 或 HTML。
如果你属于最后一种情况，请下载 Apifox 并针对项目尝试 apifox export；它可以无缝集成到 CI 任务中，从而在每次 API 发生变更时自动重新构建文档。
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。
如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。
值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。
获取专属报价与部署方案
详细的私有化部署系统架构与安全白皮书
针对您公司规模的专属报价单
免费的 1v1 专属产品演示 (Demo) 机会
