随着现代 Web 应用程序的不断发展，API 文档的生成成为了一个必不可少的任务。这其中，Swagger 是一个广泛使用的工具，用于定义、构建和文档化 RESTful APIs。然而，传统的 Swagger UI 面临着一些问题，比如它没有提供可定制性，维护难度较大，UI 不够美观等。因此，针对这个问题，出现了诸如 Redoc、Slate 等工具。
本文将介绍一个基于 Redoc 的 npm 包 @ingoclaro/redoc。该包提供了一个易于使用、高度可定制的 Swagger UI。在本文中，我们将阐述如何使用该包以及如何进行自定义配置。
安装
首先，我们需要安装 @ingoclaro/redoc。在任意位置打开命令行界面，执行以下命令即可：
npm install --save @ingoclaro/redoc
基本用法
在安装好 @ingoclaro/redoc 之后，我们就可以开始使用了。为了实现一个简单的示例，我们将首先在项目目录中创建一个 swagger.json 文件，用于定义 API。
-- -------------------- ---- -------
-
---------- --------
------- -
-------- --------- -----
---------- -------
--
---------- -
-
------ --------------------------------
-
--
-------- -
--------------- -
------ -
---------- ----- --- -- ----
-------------- -------------
------------- -
-
------- --------
----- -------
----------- -----
-------------- --- -- --- -- --------
--------- -
------- ----------
--------- -------
-
-
--
------------ -
------ -
-------------- ----------- -----------
---------- -
------------------- -
--------- -
------- --------------------------
-
-
-
--
------ -
-------------- -------- -- ----------
---------- --
--
------ -
-------------- ---- --- -------
---------- --
-
-
-
-
--
------------- -
---------- -
------ -
------- ---------
------------- -
----- -
------- ----------
--------- -------
--
------- -
------- --------
--
------ -
------- --------
-
--
------ -
------- -----
-
-
-
-
-接着，在 HTML 文件中添加一个容器元素：
<div id="redoc-container"></div>
最后，在 JavaScript 文件中引用 @ingoclaro/redoc，加载 swagger.json 并在容器元素中渲染出 Swagger UI：
import Redoc from '@ingoclaro/redoc';
const options = {
expandResponses: 'all',
};
Redoc.init('/path/to/swagger.json', options, document.getElementById('redoc-container'));这样，我们就可以在页面中看到类似于 Redoc 官网一样美观的 Swagger UI 了。值得注意的是，虽然我们只在这个示例中使用了 JSON 文件，但 Redoc 同样支持 YAML 文件的使用。在加载 YAML 文件时，只需将文件路径更改为 YAML 文件即可。
自定义配置
除了基本用法之外，@ingoclaro/redoc 还提供了一些简单的 API 以供我们进行自定义配置。考虑到篇幅的限制，本文只介绍其中的一部分。完整 API 列表请参见 官方文档。
expandResponses
expandResponses 可用于控制操作凭据中的 HTTP 响应是否默认展开。可选值包括 'all'、'success' 和 'none'。默认为 'none'。
例如，我们要将所有的响应自动展开，可以在选项对象中加入：
const options = {
expandResponses: 'all',
};scrollYOffset
scrollYOffset 用于控制锚点跳转后页面滚动的偏移量。默认为 168。
例如，我们使用了一个固定在屏幕顶部的导航栏，在锚点跳转后需要考虑到导航栏遮挡页面的问题。可以在选项对象中加入：
const options = {
scrollYOffset: 100,
};hideDownloadButton
hideDownloadButton 可以隐藏 UI 右上角的下载按钮。默认为 false。
例如，我们需要隐藏下载按钮：
const options = {
hideDownloadButton: true,
};结语
到这里，我们已经介绍了 @ingoclaro/redoc 的基本用法以及一些自定义配置。在实际的开发中，我们可以根据项目的需要对 Redoc 进行深度自定义，以便更好地展示和传达 API 文档。为了获取更多的信息，建议您阅读 Redoc 的官方文档并深入了解。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60065b49c6eb7e50355dbf93