介绍
@4geit/swg-template 是一个基于 Swagger UI 和 Handlebars.js 的前端库，可以帮助开发者快速构建适用于 RESTful API 的在线文档。此包提供了统一的 API 规范，接口风格一致，支持多种数据类型解析，同时提供了简单可配置的 UI 风格。
安装
首先，确保已在本机安装了 Node.js 和 NPM，然后在命令行输入以下命令进行安装：
npm install @4geit/swg-template --save
若须使用旧的版本，可以在命令末尾加上版本号，例如：
npm install @4geit/swg-template@1.2.3 --save
快速上手
基本用法
- 在项目中添加
swagger.json文件，其中包含你的 API 信息。 - 创建一个
index.html文件，并在其中添加如下代码：
-- -------------------- ---- -------
--------- -----
------
------
---------- ----------
-------
------
---- -------------------
------- -----------------------------------------------------------------------------------------------
--------
----- -- - -----------------
---- -----------------
------- -----------
-------- -
-----------------------------
-----------------------------------------
--
---
---------
-------
-------- 将
index.html文件部署至你的服务器并打开，你将看到一个基本的 API 文档。
定制样式
- 在项目中创建一个
swagger.css文件，添加你需要的样式。 - 在
index.html中添加一行：
<link rel="stylesheet" type="text/css" href="./swagger.css">
配置参数
以下是一些可配置的 UI 视图选项：
| 属性名 | 描述 |
|---|---|
deepLinking |
支持深度链接，可通过 URL 直接跳转到指定位置 |
displayOperationId |
在操作列表中显示操作 ID |
displayRequestDuration |
在操作列表中显示请求耗时 |
filter |
根据过滤条件过滤 API 列表 |
maxDisplayedTags |
最大显示标签数 |
showExtensions |
显示隐藏的扩展属性 |
tagsSorter |
API 标签排序方法 |
validatorUrl |
URL 链接，用于验证输入和输出 |
例如，若要开启 deepLinking，则可以通过如下方式进行配置：
-- -------------------- ---- -------
----- -- - -----------------
---- -----------------
------- -----------
------------ -----
-------- -
-----------------------------
-----------------------------------------
--
---更多的 UI 视图选项和其他配置参数，请参考官方文档：https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
示例代码
以下是一个基于 Node.js 和 Express 的完整示例：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ---- - ---------------- ----- --------- - ------------------------------ ----- ---- - ------------------ ----- --------------- - ---------------------------- ----- --- - ---------- -------------------- ---------------- ---------------------------------- ------------------------------------------- ------------ ---------------- -- -- - ------------------- ------- -- ---- ------- ---
其中，swagger.yaml 包含 API 信息。
结论
@4geit/swg-template 是一个非常有用的前端库，可以轻松创建格式化的 API 文档，让你的 API 更易于使用和调试。使你的 API 更加友好和可靠。希望这篇文章可以帮助你更好的使用它。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055ea381e8991b448dc029