如果你是一位前端开发人员，你肯定会遇到过这样的问题：当你创建一个 API 时，你需要手动编写 API 文档，然后更新这些文档。这是一项相当繁琐的任务，而且容易出现错误。
Hapi 和 Swagger 是两个开源的工具，它们可以帮助你自动创建 API 文档。在本文中，我将向你展示如何将它们结合起来，从而为你的 API 创建自动生成文档。
Hapi 是什么？
Hapi 是一个 Node.js 开发框架，它由 Walmart 创建并开源，用于创建 Web 应用程序和 API。Hapi 有一个强大的插件系统，它允许开发人员轻松地扩展应用程序的功能。
下面是一个简单的 Hapi 应用程序：
----- ---- - ----------------
----- ------ - --- ------------- ----- ---- ---
--------------
------- ------
----- ---------
-------- --------- -- -- -
------ ------ -------
-
---
---------------------- -- -
------------------- ------- --- ---------------------
---在这个例子中，我们创建了一个简单的 Hapi 应用程序，它监听 3000 端口，并定义了一个路由，当用户请求 /hello 时，它返回一个简单的字符串：“Hello world”。
Swagger 是什么？
Swagger 是一个 API 规范和工具集，它的目标是帮助开发人员和企业设计和构建更好的 API。Swagger 具有许多功能，其中最常见的是生成 API 文档。
Swagger 文档的一个很好的例子是它的在线编辑器。当你在编辑器中定义一个 API 时，它会自动生成文档，以帮助你更好地了解 API。
如何为 Hapi 创建 API 文档
我们将使用 Swagger 帮助我们自动创建 Hapi 的 API 文档。为此，我们需要安装 swagger 和 Hapi-swagger 插件。
--- ------- ------- ------------ ------
在我们安装了这些依赖项之后，我们需要对我们的应用程序进行一些修改，以便添加 Swagger。
----- ---- - ----------------
----- ----- - ----------------- -- --------
----- ------ - ------------------ -- --------
----- ----------- - ------------------------
----- ------ - --- ------------- ----- ---- ---
----- -------------- - -
----- -
------ ----- --- ---------------
-------- -------
-
--
----- ------------- - -
------
-------
-
------- ------------
-------- --------------
-
--
-------------------------------------- -- -
--------------
------- ------
----- ---------
-------- --------- -- -- -
------ ------ -------
--
-------- -
----- --------
------------ ---- -------
------ ---- --- --- ----- -- ---- ---------
--------- --
-
---
---------------------- -- -
------------------- ------- --- ---------------------
---
---在这个例子中，我们添加了一些新的依赖项 Inert 和 Vision，这些是 Swagger 所需的。我们还定义了 swaggerOptions 对象，它允许我们定义一些 Swagger 的元数据，例如标题和版本。
在 pluginOptions 数组中，我们添加了 Hapi-swagger 插件，并将 swaggerOptions 作为选项传递。
最后，我们使用 options 对象定义了我们的路由。这个对象包含一些元数据，例如标签、描述和笔记。这些元数据将帮助 Swagger 自动生成文档。
参数校验
Swagger 可以自动根据路由参数定义自动生成参数校验文档，开发者只需要在 route.metho.options 配置 validate 参数即可，示例代码如下：
--------------
------- -------
----- ----
-------- --------- -- -- -
----- - ----- --- - - ----------------
----- ----- - ------- ---------
----- ---- - ---- --- ------ ----- -----
------ ---------- ----------
-
-------- -
----- --------
------------ ---- ----- ---- ---- -------------
------ ---- --- --- ----- -- ---- ------- ---- ---- --- -----
--------- -
-------- -
----- ----------------------------------------- -------
---- --------------------------------------------------------- -----
-
-
-
---其中，我们在 validate 参数中传入 payload 对象，对象中存放了两个参数 name 和 age 的校验条件。
总结
Hapi 和 Swagger 是两个强大的工具，它们可以帮助你更轻松地创建 Web 应用程序和 API，并自动生成文档。在本文中，我们学习了如何将它们结合起来创建自动生成文档的 API。使用 Hapi 和 Swagger，你可以将更多的时间用于编写代码，而非手动编写文档。
完整源码请查看这个 GitHub repo。
来源：JavaScript中文网 ，转载请联系管理员！ 本文地址：https://www.javascriptcn.com/post/65026e6195b1f8cacdfb8676