如何使用CLI生成API接口文档

时间：2026-08-15 13:29

一旦有人修改了接口定义或 API 规范，却忘记重新生成参考文档，接口文档就会马上失效。最有效的解决办法，是不要再把文档生成当成手动操作。只要通过一条命令就能自动生成 API 文档，你就可以把这个命令接入 CI，在每次代码合并时自动执行，确保文档始终与接口保持一致。在终端里完成这件事还有更多优势。CL

一旦有人修改了接口定义或 API 规范，却忘记重新生成参考文档，接口文档就会马上失效。最有效的解决办法，是不要再把文档生成当成手动操作。只要通过一条命令就能自动生成 API 文档，你就可以把这个命令接入 CI，在每次代码合并时自动执行，确保文档始终与接口保持一致。

在终端里完成这件事还有更多优势。CLI 命令天然适合脚本化执行，能够留下便于审查的 diff，而且无论是 AI 助手还是 CI 运行器，都不需要人工打开浏览器就能触发整个流程。无需依赖 GUI 点击操作，也不用再反复确认“你有没有记得导出文档”。

本指南会先介绍一条通用的开源方案：如何用单条命令把 OpenAPI 文件生成独立的 HTML API 文档页面或 Markdown 文档。随后，我们会进一步讲解 Apifox CLI 方案，它可以直接从活跃项目中提取接口文档，让单一可信数据源始终与最终输出同步。如果你想系统了解背景信息，也可以继续阅读我们关于顶级 REST API 接口文档工具以及免费 API 接口文档工具的相关综述。

跟着本文操作，你只需要准备一项内容：一个 OpenAPI 3.x 文件。大多数命令同时兼容 openapi.yaml 和 openapi.json。

使用 Redocly CLI 构建 HTML 参考页面

Redocly CLI 是把 OpenAPI 描述快速转换成美观且独立 HTML 页面的一种高效方式。它基于 Redoc 渲染你的接口定义或 API 规范，并将样式、脚本与内容全部打包进一个文件中。生成后的 API 参考文档可以部署到任意站点，也可以直接发送给团队成员查看。

全局安装它，或者直接跳过安装，通过 npx 执行：

npm install @redocly/cli -g

然后让命令指向你的接口定义或 OpenAPI 规范文件：

redocly build-docs openapi.yaml

默认情况下，它会在当前目录生成 redoc-static.html。在浏览器中打开这个文件，你会看到一份完整的三栏式 API 参考文档页面。若你想自定义文件名或输出路径，可以使用 --output：

redocly build-docs openapi.yaml --output docs/index.html

整个流程非常直接：一个输入文件、一条命令、一个 HTML 输出结果。它支持 Swagger 2.0 以及 OpenAPI 3.0/3.1，因此大多数现有 API 定义无需额外修改就能直接渲染。需要注意的是，它的定位主要是生成参考文档页面，不包含长篇使用指南、教程或入门文档等更丰富的内容结构。

使用 Widdershins 生成 Markdown

有些场景下你并不需要 HTML 页面。你可能更需要能放进文档站、静态站点生成器，或代码仓库 docs/ 目录中的 Markdown 文件。Widdershins 可以将 OpenAPI、Swagger 或 AsyncAPI 定义转换为与 Slate 兼容的 Markdown 文档。

先通过 npm 安装：

npm install -g widdershins

然后执行转换命令，并使用 -o 将结果输出到指定文件：

widdershins openapi.yaml -o api.md

如果省略 -o，Widdershins 会把输出直接打印到标准输出（stdout），这对于你需要通过管道把内容传递给其他工具时非常方便。你还可以为代码示例配置语言标签页：

widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md

如果你的接口文档工作流以 Markdown 为核心，Widdershins 会是一个非常实用的选择。如果你正在搭建更完整的 Markdown 导出体系，我们关于支持 Markdown 导出的接口文档生成器指南也涵盖了相关配套工具。Redocly 与 Widdershins 的共同局限在于：它们读取的都是静态文件。如果你的 API 规范主要维护在设计工具中，而本地磁盘文件没有同步更新，那么最终生成的文档就可能还是旧版本的接口定义。

使用 Apifox CLI 从活跃项目中生成文档

这正是集成式方案的价值所在。Apifox 虽然不是开源工具，但它的免费版配合 apifox-cli，可以为你提供一套更完整的 API 文档自动化方案，不需要再把多个零散工具勉强拼接起来：接口定义、数据模型和手写文档都保存在同一个项目中，CLI 可以按需直接导出。由于导出读取的是团队正在维护的同一份数据源，因此可以有效避免文档与接口版本不一致的问题。

先通过 npm 安装 CLI：

npm install -g apifox-cli

如果你是第一次配置环境，可以参考我们的 Apifox CLI 安装指南，确认 Node 版本和 PATH 设置是否正确。之后，使用个人访问令牌完成一次登录认证：

apifox login --with-token

Token 会被本地保存，因此后续调用通常不需要每次重复传入。从这一步开始，几乎所有操作都会围绕项目 ID 进行。在执行任意命令前，都可以先追加 --help 查看当前版本支持的准确参数与用法。

将规范导入到项目中

如果你的 API 目前已经以 OpenAPI 文件的形式存在，那么先把它导入到项目中，这样 CLI 才有可导出的内容来源：

apifox import --help apifox import --project--format openapi --file ./openapi.json

apifox import 支持 OpenAPI 3.x、Swagger 2.0、Postman 以及 Apifox 格式，因此你也可以用相同方式导入 Postman 集合，或现有的 Apifox 导出文件。导入完成后，这份规范就会成为后续所有文档输出所依赖的实时数据源。

导出易于阅读的文档

这是最核心的命令之一。apifox export 支持导出 OpenAPI、HTML、Markdown 或 Postman 格式，所以建议你先执行 --help，确认当前 CLI 版本支持的具体格式与输出参数。下面是将项目接口文档导出为 Markdown 的方式：

apifox export --help apifox export --project--format markdown --output ./api-docs.md

打开 api-docs.md 后，你会获得一份根据项目当前状态即时生成的完整 API 参考文档。如果你需要 HTML 格式，只需调整一个参数：

apifox export --project--format html --output ./api-docs.html

当你需要交付一份便于下游系统继续使用的标准规范文件时，也可以重新导出为 OpenAPI：

apifox export --project--format openapi --output ./openapi.json

如果你的项目中包含多个服务，而你只希望为其中某一部分生成接口文档，导出功能通常也支持进一步缩小范围。请查看当前版本的 apifox export --help，确认 scope 与 ID 相关参数，因为借助这些选项，同一个项目可以分别输出不同服务对应的文档文件。

管理编写的指南，而不只是参考文档

仅依靠根据数据模型自动生成的 API 参考文档，其实还远远不够。另一部分同样关键的内容，是说明性文档，比如快速开始、认证流程演示以及迁移说明。在 Apifox 中，这些内容以 Markdown 文档形式保存在项目文档树里，而 CLI 则通过 doc 命令组对它们进行管理。

首先，请先查看该命令组的帮助信息，确认你当前版本支持的具体 flags 参数：

apifox doc --help apifox doc list --project

继续往下操作时，整体逻辑和 CLI 中其他命令类似：先针对你的项目执行命令，获取返回的 JSON 结果，再根据其中的 agentHints.nextSteps 继续下一步处理。如果某条命令需要 JSON 负载，CLI 还会先输出它所期望的数据模型，并在真正发送前依据该模型校验你的文件。这样一来，缺失字段或格式问题可以在本地提前发现，不必等到请求失败后再回过头排查。至于更具体的 validate 子命令，可以查看 apifox cli-schema --help。

发布文档站

当 API 参考文档和配套指南都准备完成后，你同样可以通过终端管理已发布的文档内容。这部分主要由两个命令负责，建议先阅读它们的帮助说明，避免在参数上盲目试错：

apifox docs-site --help apifox shared-doc --help

这里有一个很容易混淆的命名区别：doc 指的是项目 API 树中的 Markdown 文档；docs-site 用于管理托管的公开文档站点；而 shared-doc 则用于管理可分享的文档链接。如果你希望通过 CLI 定义并维护一个公开文档站，而不是在 UI 界面里手动配置，请使用 docs-site；如果你只需要生成一个可以分享给合作伙伴的文档链接，那么应使用 shared-doc。这种方式的优势在于，文档发布流程也变成了可脚本化的步骤：当接口定义发生变化时，你只需重新导入或更新项目，然后再次运行发布命令，托管文档就会自动同步更新。

将其接入 CI

之所以推荐在 CLI 中执行这些 API 文档生成命令，关键就在于它具备高度可重复性。只要本地能够稳定运行，迁移到持续集成流水线（CI pipeline）中通常也会非常顺畅。下面给出的，就是一套尽量精简的 GitHub Actions 示例步骤：它会在每次 push 时，自动重新生成并提交 Markdown 接口参考文档。

name: Regenerate API docs run: | npm install -g apifox-cli apifox login --with-token ${{ secrets.APIFOXTOKEN }} apifox export --project ${{ secrets.APIFOXPROJECT }} --format markdown --output ./docs/api-docs.md

即使你把这里的命令替换成 redocly build-docs 或 widdershins，整体工作流本质上也完全一致。API 文档维护不再是某个人必须记得手动完成的琐碎工作，而会变成一种能够自动生成的构建产物。若想查看更完整的命令说明，可以继续参考 Apifox CLI 完整指南。

常见问题

错误或缺失的项目 ID。每次调用 Apifox 的 export、doc 和 docs-site 时，通常都需要指定 --project 。这个 ID 位于项目设置中，并不是你平时看到的项目名称。如果命令报错且提示与项目相关的问题，这通常就是最常见的根本原因。

CI 中没有配置 Token。apifox login 会把 Token 存储在当前执行命令的机器上。但在全新的 CI runner 中，并不存在之前已保存的 Token，所以在执行任何导出操作之前，你必须在同一个 job 中先运行 login --with-token。同时务必将 Token 存放在 secret 中，不要直接写入工作流文件。

导出的文件内容已经过时。Redocly 和 Widdershins 会直接读取你传入的本地文件。如果你的 openapi.yaml 本身就不是最新版本，那么生成出的接口文档自然也会过时。这也是 Apifox 方案重点解决的问题：它直接从活跃项目中导出，而不是依赖磁盘中的旧文件，因此更能避免文档与实际接口不一致。

凭记忆猜测参数（flag），而不是先查看 --help。export、doc、docs-site 和 shared-doc 的具体参数，可能会随着 CLI 版本变化而有所不同。更稳妥的做法，是先执行 apifox --help，再按照实际输出结果操作，而不是依赖模糊印象去猜。这个动作只需要几秒钟，却往往能避免整个构建流程失败。

总结

通过命令行生成 API 文档，核心在于根据实际场景选择合适的输出方式。若你需要一份独立的 HTML API 参考文档，Redocly CLI 是非常直接的选择；如果你想为文档站或仓库生成 Markdown，Widdershins 会更加合适；而当你希望把 API 参考文档、手写指南以及已发布的文档站都统一从同一个活跃数据源中导出时，Apifox CLI 往往是更完整的解决方案。最后这一类方式最大的优势，就是能让接口文档持续保持准确，因为导出内容与团队实际维护的项目数据始终保持同步。

本文提到的每一条命令都支持脚本化执行，这也意味着它们非常适合接入 CI/CD。只要配置一次，后续每当接口发生变更，文档就能自动重新生成。你可以下载 Apifox 获取 CLI，并在自己的项目中尝试 API 文档导出流程，或者进一步了解 Apifox 如何融入 API-first 开发工作流。