如何通过 CLI 生成接口文档

一旦有人修改了接口定义/规范却忘记重新生成参考文档，接口文档就会立即失效。解决方法是不要再将文档编写视为一个手动步骤。如果只需一条命令即可生成文档，您就可以将该命令集成到 CI 中，使其在每次合并时自动运行。

在终端中进行操作还有其他好处。命令是可编写脚本的，它们会留下可供审查的 diff，而且 AI 袋里或 CI 运行器无需任何人打开浏览器即可触发它们。无需在 GUI 上点击，也无需再问“你记得点击导出了吗”。

本指南将首先介绍通用的开源路线：如何通过单条命令将 OpenAPI 文件转换为独立的 HTML 参考页面或 Markdown 文件。接着，我们将深入探讨 Apifox CLI 路线，它可以直接从运行中的项目中提取文档，从而使单一可信源与输出内容保持同步。如果您想了解更多背景信息，可以参阅我们对顶级 REST API 接口文档工具以及值得了解的免费 API 接口文档工具的综述。

紧跟本指南只需准备一样东西：一个 OpenAPI 3.x 文件。大多数命令都同时支持 openapi.yaml 或 openapi.json。

使用 Redocly CLI 构建 HTML 参考页面

Redocly CLI 是将 OpenAPI 描述转换为美观、独立的 HTML 页面最快捷的方法。它使用 Redoc 渲染您的接口定义/规范，并将所有内容（样式、脚本和内容）写入一个文件中，您可以将其托管在任何地方，或者通过电子邮件发送给同事。

全局安装它，或者跳过安装并使用 npx 运行：

npm install @redocly/cli -g

然后将其指向您的接口定义/规范文件：

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 描述，因此大多数现有的接口定义/规范无需修改即可直接渲染。妥协之处在于范围：build-docs 仅提供参考页面，别无其他。长篇指南、教程和入门页面都不在此范围内。

使用 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 为你提供了一个替代方案，让你无需将各个独立的工具拼凑在一起：你的接口、数据模型以及编写的文档都保存在同一个项目中，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 以查看你当前版本所支持的确切格式和输出标志，然后将项目的接口文档导出为 Markdown：

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

打开 api-docs.md，你就会得到一份根据项目当前状态生成的完整参考文档。想要 HTML 格式？只需修改一个标志：

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

当你需要一个便携的规范来交付给下游时，也可以重新导出为 OpenAPI 格式：

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

如果你的项目包含多个服务，并且你只想为其中一部分生成文档，导出功能支持缩小范围。请检查你当前版本的 apifox export --help 以获取 scope 和 ID 标志，因为通过这种方式，单个项目可以为每个服务都输出一个文档文件。

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

根据数据模型生成的参考文档还远远不够。另一半是说明性文字：入门指南、auth 演练和迁移说明。在 Apifox 中，这些内容以 Markdown 文档的形式存在于项目的文档树中，而 CLI 则使用 doc 命令组来管理它们。

首先，请阅读该命令组的帮助信息，以便了解您当前版本所支持的具体参数 (flags)：

apifox doc --help apifox doc list --project

接下来，操作流程与 CLI 中的其他操作类似：针对您的项目运行命令，读取 JSON 结果，并按照其返回的 agentHints.nextSteps 进行操作。当命令需要 JSON 负载时，CLI 可以打印其期望的数据模型，并在发送任何内容之前对照该模型验证您的文件。这样，您就可以在本地计算机上捕获缺失的字段，而不是在调用失败时才发现。请查看 apifox cli-schema --help 以获取具体的 validate 子命令。

发布文档站

当参考文档和指南准备就绪后，您也可以在终端中管理已发布的文档。这由两个命令负责，先阅读它们的帮助信息可以避免盲目猜测参数：

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

需要注意一个容易混淆的命名问题：doc 是项目 API 树中的 Markdown 文档，docs-site 用于管理托管的公开文档站，而 shared-doc 用于管理可共享的文档链接。当您希望通过终端定义一个公开站点（而不是在 UI 界面中点击配置）时，请使用 docs-site；当您只需要一个链接来分享给合作伙伴时，请使用 shared-doc。这样做的好处是，发布过程变成了一个脚本化的步骤：当您的接口定义发生变更时，您只需重新导入或编辑项目，然后再次运行发布命令，托管的文档就会自动更新。

将其接入 CI

在 CLI 中运行这些命令的原因是为了实现可重复性。一旦这些命令可以在本地正常工作，它们就可以在流水线（pipeline）中运行。一个在每次推送（push）时重新生成并提交 Markdown 参考文档的最小化 GitHub Actions 步骤如下所示：

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，其流程也是完全相同的。编写文档不再是某个人必须记住去做的繁杂事务，而是变成了一个可以自动重新生成的构建产物。有关完整的命令参考，请参阅 Apifox CLI 完整指南。

常见问题

错误或缺失的项目 ID。 每次调用 Apifox 的 export（导出）、doc 和 docs-site 时都需要指定 --project <projectId>。该 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 <command> --help 并根据其输出的内容进行操作，而不是靠模糊的记忆去猜参数。这只需花费两秒钟，却能避免构建失败。

总结

从终端生成 API 文档，关键在于选择合适的输出格式。当你需要一个独立的 HTML 参考文档时，可以选择 Redocly CLI；当你需要为文档站生成 Markdown 时，可以选择 Widdershins；而当你需要将参考文档、手写指南以及已发布的网站全部从同一个活跃的数据源中导出时，Apifox CLI 是最佳选择。最后一种方案能确保你的文档时刻保持准确，因为导出的内容与你团队正在编辑的内容源自同一个项目。

此处介绍的每一个命令都是可脚本化的，这意味着它们都适用于 CI。只需设置一次，你的文档就会在每次变更时自动重新生成。下载 Apifox 以获取 CLI 并针对你自己的项目尝试导出流程，或者阅读如果还需要延伸了解 Apifox 如何融入 API-first 工作流的介绍。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。