随着 API 的普及和全面推广，越来越多的前端开发人员需要用到 API 文档。而一份清晰、易读的 API 文档不仅能大幅减少开发者的学习时间，同时也能够提高开发者的工作效率。因此，在编写 API 文档时，常常需要使用到一些工具，如 redoc-cli。
简介
redoc-cli 是一款基于 ReDoc 的命令行工具，可用于生成漂亮的静态 HTML 页面，并将您的 OpenAPI 或 Swagger 规范显示为可读的 API 文档。 它支持许多不同的自定义选项，可让您轻松地调整输出，并根据需要添加任意页头和页脚。
安装
在您的项目目录下运行以下命令安装 redoc-cli：
npm install -g redoc-cli
使用
以下是生成 API 文档的基本用法：
redoc-cli bundle path/to/your/swagger.yaml
其中，path/to/your/swagger.yaml 为您的 Swagger 规范所在的路径。
您可以使用以下命令来指定输出文件的名称和路径：
redoc-cli bundle path/to/your/swagger.yaml -o path/to/output.html
此外，您可以使用 --options 选项来指定 redoc-cli 的配置选项。以下是一些常用的配置选项：
- theme：用于设置页面主题的名称
- options.noAutoAuth：用于设置是否禁用自动授权
- options.hideLoading：用于设置是否隐藏加载动画
例如，以下命令将创建一个名为 output.html 的 API 文档，并指定了主题和一些配置选项：
redoc-cli bundle path/to/your/swagger.yaml -o output.html --options.theme colors --options.noAutoAuth true --options.hideLoading true
示例
以下是一个示例 Swagger 规范：
-- -------------------- ---- ------- -------- ----- ----- ------ --- ---- ------------ -- ------ ---- ---- -------- ------- --------- ----- -------- - ------- ------ ------- ---- -------- ---- --- ------ ------------ -------- - ---- -- --- ------ --------- - ------------------ ---------- ---- ------------ ----------- ----------展开代码
您可以在您的项目目录下创建一个名为 swagger.yaml 的文件，并将上述内容复制到该文件中。
接下来，在终端中输入以下命令，即可生成 API 文档：
redoc-cli bundle swagger.yaml -o output.html
这将在您的目录下创建一个名为 output.html 的文件。您可以在浏览器中打开它，以查看生成的文档。
总结
redoc-cli 是一款功能强大的命令行工具，可以帮助前端开发人员快速地生成漂亮的 API 文档。本文介绍了 redoc-cli 的安装和基本用法，同时也提供了一些配置选项和示例代码。希望本文对您有所帮助，能够让您更加便捷地编写 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5f091d24403f2923b035c00b
