在前后端分离的项目中，对于后端 API 接口文档的编写和说明显得至关重要。而 Swagger UI 是一个开源的 API 文档工具，它可以快速构建和调试 API 文档。本文将介绍如何使用 Hapi.js 和 Swagger UI 创建 API 文档并且使用它，让开发者更加高效的进行 API 的开发和维护。
Hapi.js 简介
Hapi.js 是一个现代化、安全、高性能的 Node.js Web 应用程序框架。它可用于构建单页应用程序、APIs 以及网站。该框架使用了一种插件化的方式以便于功能的扩展，同时它也是一个高度可定制的框架。
在接下来的实践中，我们将使用 Hapi.js 构建一个简单的 API，同时使用 Swagger UI 自动生产 API 文档。
安装与配置
安装 Hapi.js
在开始之前，我们需要确认已经安装了 Node.js 和 npm，我们可以使用以下命令来安装 Hapi.js：
npm install @hapi/hapi
安装 Swagger UI
我们通过以下命令安装 Swagger UI：
npm install swagger-ui-express
配置 Hapi.js
我们来创建一个简单的 Hapi.js 服务器，接下来将添加一个 API 并使用 Swagger UI 为它生成 API 文档。首先，我们创建一个 index.js 文件并输入以下内容：
-- -------------------- ---- -------
---- --------
----- ---- - ----------------------
----- --------- - ------------------------------
----- ---- - ------------------
----- ------ - -------------
----- -----
----- -----------
---
----- ----- - ----- -- -- -
-- --------
--------------
------- ------
----- ---------
-------- --------- -- -- -
------ ------- --------
-
---
-- ------- -- --
----- --------------- - ----------------------------
-----------------
-
------- ----------------
-------- -
--------------- -
---- ---------------------
--
--
--
-
------- ----------------
-------- -
----------- ---------------------
--
--
---
-- -----
----- ---------------
------------------- ------- -- ---------------------
--
--------我们首先创建了一个 Hapi.js 服务器，并且注册了一个测试路由。接下来我们通过引入 yamljs 模块加载 Swagger YAML 文件，并注册 Swagger UI 插件。我们使用 await 启动服务器并在控制台显示运行端口。在此之前，我们需要创建一个 swagger.yaml 文件并输入以下内容：
-- -------------------- ---- -------
-------- -----
-----
-------- -----
------ ------- - ------- -- ---
------------ - ------ --- ----- ----- ------- - -------
----- --------------
--------
- ----
---------
- ----------------
---------
- ----------------
------
-------
----
------------ --------- - -------- --------
---------
- ----------------
----------
----
------------ - -------- ------- -- ---------
-------
----- ------
-----------
--------
----- ------
-------- ------ ------这里我们定义了一个简单的 API，其中包含了一个 GET 方法用于从 /hello 路径获取一条问候语。Swagger UI 将会在这个文件基础上生成相应的 API 文档。
注：本示例所生成的 API 文档在本机 3000 端口内运行，请确保此端口没有被占用。
使用 Swagger UI
我们现在可以运行这个服务器，并在浏览器中打开 http://localhost:3000/api-docs 来查看 Swagger UI 编制的 API 文档。Swagger UI 将在 URL /api/documentation 下生成 API 文档。这是上面配置文件中 Swagger UI 的相关配置代码部分（很重要）：
-- -------------------- ---- -------
----- --------------- - ----------------------------
-----------------
-
------- ----------------
-------- -
--------------- -
---- ---------------------
--
--
--
-
------- ----------------
-------- -
----------- ---------------------
--
--
---这里我们利用了 Hapi.js 插件机制，并将 Swagger UI 注册为插件。同时，我们设置了 swaggerDocument 使用 YAML 文件的内容，并将 URL：/api/documentation 传递给 Swagger UI 进行相关配置。
下面是 Swagger UI 的截屏：
如图，我们可以很清晰地看到我们在 swagger.yaml 文件中定义的 API 文档。而且 Swagger UI 还提供了一个交互式的测试页面，使我们可以轻松地测试我们的 API，同时可以展示我们所注册的 API 描述信息。
结论
在本文中，我演示了如何使用 Hapi.js 和 Swagger UI 快速构建和测试 API 接口，并自动生成 API 文档。这使我们能够更迅速地开发和测试 API 接口，并提高开发效率。同时，Swagger UI 可以为我们的项目提供更好的文档和可读性。如果您有相关项目的需求，我相信本文能够给您提供很好的帮助指导。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6708db5ad91dce0dc874c173