本文将介绍 Hapi.js 框架中的 hapi-swaggered 插件，该插件是一款用于自动生成 API 文档的工具。如果你正在开发一个基于 Hapi.js 的 RESTful API，那么 hapi-swaggered 插件绝对是值得尝试的。
安装 hapi-swaggered 插件
hapi-swaggered 插件可以通过 npm 来安装：
npm install hapi-swaggered --save
hapi-swaggered 插件的功能
hapi-swaggered 插件的主要功能包括：
- 自动生成 API 文档，降低文档维护成本。
- 支持 Swagger 2.0 规范，符合标准化的 API 文档规范。
- 自动生成 API 导航栏，方便查看所有接口。
- 实时同步代码注释，使 API 文档保持最新。
hapi-swaggered 插件的详细使用
第一步：引入插件
在 Hapi.js 应用中，需要在 server.register 方法中引入 hapi-swaggered 插件并配置相关参数，如下所示：
-- -------------------- ---- -------
----- ---- - ----------------
----- ------ - --- --------------
------------------- ----- ---- ---
-----------------
--------- --------------------------
-------- -
----- -
------ ---- ----
-------- -------
-
-
-- ----- -- -
-- ----- -
--------------------- -- ---- --------- -----
-
---在配置中，我们设置了 API 文档的基本信息，包括文档名称和版本号。
第二步：配置路由
接下来，需要在 Hapi.js 应用中配置所有的路由，同时，在路由配置中添加 Swagger 格式化信息，如下所示：
-- -------------------- ---- -------
--------------
------- ------
----- -------
------- -
----- -------- -- ----
------------ --- --- ---- -- --
------ ----- --- ---- -- --
-------- --------- ------ -- -
-- ---
--
-------- -
----------------- -
------------ ------------- -- ---- --
---------- -
------ - -- ----------
------------ --- --- ----
-
-
-
-
-
---此配置中，我们添加了接口的分组标签、描述和备注信息，并将 hapi-swaggered 插件的参数配置在 plugins 中。这里的 operationId 应该是唯一的，用于 API 导航栏中的链接跳转。
第三步：访问 API 文档
在 Hapi.js 应用中，可以通过 /documentation 路径来访问自动生成的 API 文档，同时可以通过配置页面中的输入框来测试接口。如下所示：
hapi-swaggered 插件的优点
代码注释与文档同步
开发者只需要在代码注释中添加 Swagger 格式化注释，而无需维护一份独立的文档。这样，当代码变更时，API 文档也会自动更新。
API 导航栏
API 导航栏能够方便开发者查看所有的接口，并进行跳转。同时，该导航栏的生成与代码分组相关，也能够方便开发者对接口进行分组。
总结
本文介绍了 Hapi.js 框架中的 hapi-swaggered 插件，插件的主要功能是自动生成 API 文档，使文档维护更便捷。同时，插件支持 Swagger 2.0 规范，并自动生成 API 导航栏，更方便了对接口的查看和维护。
如果你正在开发一个基于 Hapi.js 的 RESTful API，那么 hapi-swaggered 插件一定是值得尝试的。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/649f7e5748841e9894bd74c8