在前后端分离的开发模式中，API 文档的编写和管理变得越来越重要。Swagger 是一个用于设计、构建、记录和使用 RESTful API 的开源工具。Swagger UI 是 Swagger 的一个插件，可以方便地展示 API 文档信息，帮助开发者更好地了解和使用 API。本文主要介绍如何使用 Hapi.js 框架来实现 Swagger UI，让您的 API 更加易于使用。
Hapi.js 简介
Hapi.js 是一个由 WalmartLabs 团队大力开发的 Node.js web 应用框架。它的目标是提供一个可扩展、高度定制、轻松编写测试用例的框架，同时保持简单。Hapi.js 的优势在于它具有可扩展性、可定制性和良好的性能。如果您想了解更多关于 Hapi.js 的信息，可以查看官方文档。
Swagger UI 的使用
Swagger UI 提供了一种可视化的方式，展示 API 的信息。它可以让开发人员更轻松地了解 API 的各种方法和定义。同时，Swagger UI 还提供了许多额外的功能，如请求构建器和测试等，助力开发者更好地了解 API 的情况。
您可以使用 Swagger UI 的官方托管服务在线展示 API 文档。不过，如果您希望将 Swagger UI 与您的 API 文档结合使用，则需要在自己的服务器上安装 Swagger UI。
安装 Swagger UI
在使用 Swagger UI 之前，您需要在 Node.js 环境下安装 Swagger UI。可以使用以下命令来安装 Swagger UI。
npm install swagger-ui-dist
上述命令将会在您的项目环境中，安装 Swagger UI 的所有必要文件。
实现 Swagger UI
在安装 Swagger UI 后，我们可以在 Hapi.js 应用中添加 Swagger UI 的路由。下面是一些常见的 Swagger UI 路由示例。
-- -------------------- ---- -------
----- ---- - ----------------
----- ----- - -----------------
----- ------ - ------------------
----- ----------- - ------------------------
----- ---- - ---------------------
----- ------ - --- -------------
----- ------------
----- ----
---
----- ---- - ----- -- -- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ----- --- ---------------
-------- -------------
--
-
-
---
--------------
-
------- ------
----- ----
-------- -
------------ ------- ----------
----- --------
-------- -- -- - ------ -------- -- --- ---- ----- -
--
--
-
------- ------
----- -----------------
-------- -
------------ ------- ------- -- ------
----- --------
----- ------
-------- --------- -- -- -
------ ----------------------
-
--
--
-
------- ------
----- ----------------------
-------- -
------------ -------- -- --------
----- --------
----- ------
-------- -
---------- -
----- -------------------------------
-------- ------
------ ------
-
-
--
--
---
----- ---------------
------------------- ------- --- ---------------------
--
-------------------------------- ----- -- -
-----------------
----------------
---
-------上述代码中，我们首先添加了 Inert 和 Vision 插件，这是必要的步骤。接着，我们注册了 HapiSwagger 插件，并设置了 API 文档的标题和版本号。
然后，我们添加了三个路由:
用于返回应用首页的路由
用于返回 Swagger UI 页面的路由
用于返回 Swagger UI 静态资源的路由
在编写 Swagger UI 页面时，我们可以使用 handlebars 模板来渲染静态页面。在示例代码中，我们将 handlebars 模板命名为 swagger.html。
-- -------------------- ---- -------
--------- -----
------
------
----- ----------------
------------------------
----- ---------------- --------------- ---------------------------------
----- ---------- ---------------- ----------------------------------- ------------- --
----- ---------- ---------------- ----------------------------------- ------------- --
-------
---- -
----------- -----------
--------- -------------------------
----------- -------
-
--
---------
------- -
----------- --------
-
--------
-------
------
---- ----------------------
------- -----------------------------------------------
------- ----------------------------------------------------------
--------
----- -- - -----------------
---- ----------------
------- --------------
------------ -----
-------- -
-----------------------------
-------------------------
--
-------- -
-----------------------------------
--
------- -------------
------------- -----------------------------------------
------------- -------
---------------------- ----------
------------------- -----
---
--------- - ---
---------
-------
-------在 handlebars 模板中，我们通过 <div> 元素来定义 Swagger UI 的容器。接着，我们引入了 Swagger UI 的相关静态资源文件，并设置 url 属性为 /swagger.json。注意：要将此 URL 修改为您的 API 文档的 URL。
最后，我们在 script 标签中创建了一个 SwaggerUIBundle 实例，将 Swagger UI 和我们的 API 文档捆绑在一起。在创建实例时，我们可以指定一些其他配置参数，如 deepLinking、validatorUrl 和 docExpansion 等。这些参数的作用可以在 Swagger UI 文档中查看到。
启动应用程序
现在，我们已经完成了整个应用程序的编写。你可以在终端中输入以下命令，启动应用程序。
node app.js
如果一切正常，Swagger UI 应该可以通过访问 http://localhost:3000/documentation URL 地址来显示。您应该能够看到一个与您 API 中定义一致的 Swagger UI 页面。这个页面将显示您定义的所有端点、参数、请求体和响应。您可以通过 Swagger UI 来轻松测试 API。
结论
在本文中，我们介绍了如何使用 Hapi.js 框架来实现 Swagger UI，并提供了示例代码来帮助您了解将两者结合使用的方式。通过使用 Swagger UI，您可以轻松地记录和测试 API，提高应用开发效率。如果您正在寻找一种轻量而优雅的框架来开发和管理 API，那么 Hapi.js 会是一个不错的选择。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/66f766abc5c563ced59a0a6a