Swagger 是一个流行的 API 开发框架，它允许我们使用可读性强、可视化的格式来定义和文档化 RESTful API。HapiJS 是一种非常受欢迎的 Node.js web 应用程序框架，它提供了一个强大的基础设施来创建可维护和可扩展的应用程序。结合使用这两个框架，我们可以轻松地定义和文档化我们的 HapiJS RESTful API。
安装 Swagger
在 HapiJS 中使用 Swagger，我们需要先安装 swagger 插件到 HapiJS 应用程序中：
npm install hapi-swagger
使用 Swagger 插件
安装完成插件后，我们需要配置 HapiJS 应用程序，以便它可以使用 Swagger 插件来定位我们的 API 文档，也就是 Swagger JSON 文件。
-- -------------------- ---- -------
----- ---- - ----------------
----- ----- - -----------------
----- ------ - ------------------
----- ----------- - ------------------------
----- ---- - ---------------------
----- ------ - --- -------------
----- ------------
----- ----
---
----- -------- ------- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ---- ---------------
-------- ------------
-
-
-
--
--------------
------- ------
----- ----
-------- --------- -- -- -
------ ------ -------
-
---
----- ---------------
-
--------在 HapiJS 应用程序中，我们需要在 register 方法调用中添加 swagger 插件 - HapiSwagger。在这个例子中，我们还通过 info 参数指定了文档的名称和版本。在 options 参数中可以设置更多的参数来定制 Swagger 的文档。
添加 Swagger 注释
通过在 API 定义中添加特殊注释 Joi，我们可以使用 Swagger 来解析 HapiJS 验证规则，并将其与 API 文档一起显示。
-- -------------------- ---- -------
--------------
------- ------
----- ------------
------- -
----- --------
------------ ---- ---- -- -----
------ -------- - ---- ---- --- --------- -----
--------- -
------- -
--- -------------------------------------------------- -- -- --- --------
-
--
--------- -
------- ------------
----- ------------------------
---- ----------------------------------
------ -----------------------
--
-
--
-------- --------- -- -- -
----- -- - ------------------
----- ---- - ----------------- -- ------- --- -------
------ -----
-
---在 config 参数中，我们可以为每个 API 定义定义 Swagger 注释。在这个例子中，我们使用了 tags、description、notes、validate 和 response 注释来定义一个简单的 GET API，用于根据 ID 获取用户信息。其中，validate 注释定义了参数的验证规则，response 注释定义了返回结果的结构。
产生 Swagger 文档
Swagger JSON 文件可以由 Swagger UI 在运行时自动生成，我们可以使用 Swwgger UI 来查看并测试我们的 API 文档。
server.route({
method: 'GET',
path: '/doc/swagger.json',
handler: (request, h) => {
const swaggerJSON = JSON.parse(require('fs').readFileSync('./swagger.json'));
return swaggerJSON;
}
});在这个例子中，我们定义了另一个 GET API 来返回 Swagger JSON 文档。在这里，我们从本地文件系统中读取 Swagger JSON 文件并返回它的内容。
使用 Swagger UI
安装 Swagger UI：
npm install swagger-ui-dist
在应用程序中使用它：
-- -------------------- ---- -------
--------- -----
------
------
----- ----------------
-------------- ----------
----- ---------------- -----------------------------------------
------- -------------------------------------------------------
------- ------------------------------------------------------------------
-------
------
---- ----------------------
--------
------------- - -------- -- -
----- -- - -----------------
---- --------------------
------- --------------
-------- -
-----------------------------
-------------------------
--
------- ------------------
---
--------- - ---
-
---------
-------
-------在这个例子中，我们在 HTML 文件中添加了 Swagger UI 的引用。在 window.onload 方法中，我们初始化了 Swagger UI 设置。在这里，我们设置了基本 URL 和显示 Swagger UI 的 DOM 元素的 ID。
结论
在 HapiJS 应用程序中使用 Swagger 来文档和测试 RESTful API，可以帮助我们更好地管理和维护应用程序。Swagger 提供了一个简单的方式来定义、文档化和测试 API，并且与 HapiJS 好的集成性，让我们的工作变得更加高效。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/66fb9efe44713626015f95f2