Hapi.js 是 Node.js 的一个开源框架，它可以帮助我们快速构建可扩展的 Web 应用程序。在 Hapi.js 中，我们可以使用 hapi-swagger 插件来自动生成 API 文档，这样我们就可以更加方便地管理和维护我们的 API 文档。
在本文中，我们将介绍如何使用 hapi-swagger 插件来自动生成 API 文档，并提供一些示例代码和指导意义，帮助你更好地理解和应用这个插件。
安装 hapi-swagger 插件
在开始使用 hapi-swagger 插件之前，我们需要先安装它。我们可以使用 npm 命令来安装 hapi-swagger 插件：
npm install hapi-swagger
配置 hapi-swagger 插件
安装好 hapi-swagger 插件后，我们需要在 Hapi.js 应用程序中配置它。我们可以在 Hapi.js 应用程序的启动文件中添加以下代码来配置 hapi-swagger 插件：
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - -----------------------
----- ------ - ------------------------
----- ----------- - ------------------------
----- ------ - -------------
----- -----
----- -----------
---
----- ---- - ----- -- -- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ---- ----
-------- -------
-
-
-
---
----- ---------------
------------------- ------- --- ---------------------
--
-------在上面的代码中，我们首先引入了 Hapi.js、Inert、Vision 和 HapiSwagger 这些模块。然后，我们使用 Hapi.server() 方法创建了一个 Hapi.js 服务器，指定了端口号和主机名。
接着，我们使用 await server.register() 方法注册了 Inert、Vision 和 HapiSwagger 这三个插件。其中，Inert 和 Vision 插件是 hapi-swagger 插件的依赖项，需要一起安装和注册。
在注册 HapiSwagger 插件时，我们还可以通过 options 参数来指定一些配置选项。在上面的代码中，我们指定了 API 文档的标题和版本号。
最后，我们调用 await server.start() 方法启动服务器，并在控制台输出了服务器的地址。
自动生成 API 文档
完成了配置 hapi-swagger 插件的工作后，我们就可以开始使用它来自动生成 API 文档了。
假设我们有一个简单的 API，它包含了一个 GET 请求和一个 POST 请求：
-- -------------------- ---- -------
--------------
------- ------
----- ----------------
-------- --------- -- -- -
------ ------- -------------------------
-
---
--------------
------- -------
----- ---------
-------- --------- -- -- -
----- ---- - ----------------
------ -------- ----- -------------------------
--
-------- -
--------- -
-------- ------------
----- ------------------------
------ -------------------------------
--
-
-
---使用 hapi-swagger 插件，我们可以在 API 中添加一些注释和元数据，来描述 API 的参数、响应和其他信息。例如，我们可以在 GET 请求的路由中添加以下注释：
-- -------------------- ---- -------
--------------
------- ------
----- ----------------
-------- --------- -- -- -
------ ------- -------------------------
--
-------- -
------------ ---- ----- -- - ------
------ ---- ---- --------- -- ----------
----- --------
--------- -
------- ------------
----- ---------------------------------------- ---- -- --- ------
--
--
-------- -
--------------- -
---------- -
------ -
------------ ----------
------- ------------
--
------ -
------------ ---- ---------
------- ------------
----------- --------------------------
------ ------------------------- ----------
-------- ----------------------------- ------- ------------
--
-
-
-
-
-
---在上面的代码中，我们在 options 参数中添加了一些注释和元数据，来描述 GET 请求的路由。其中，description、notes 和 tags 属性是 hapi-swagger 插件的标准属性，用来描述 API 的基本信息和分类。
validate 属性是 Hapi.js 的一个内置属性，用来验证请求参数。在这里，我们使用 Joi 对请求参数进行了验证，并添加了一些描述信息。
plugins 属性是 hapi-swagger 插件的一个自定义属性，用来描述 API 的响应和其他信息。在这里，我们使用 responses 属性来描述 GET 请求的响应。其中，'200' 和 '400' 是响应的状态码，description 属性是响应的描述信息，schema 属性是响应的数据结构。
类似地，我们也可以在 POST 请求的路由中添加注释和元数据：
-- -------------------- ---- -------
--------------
------- -------
----- ---------
-------- --------- -- -- -
----- ---- - ----------------
------ -------- ----- -------------------------
--
-------- -
------------ ------- - --- ------
------ ---- ---- --- ----- ---------- --- ----------
----- --------
--------- -
-------- ------------
----- ---------------------------------------- ---- -- --- -------
------ ------------------------------------------------ ----- -- --- ------
--
--
-------- -
--------------- -
---------- -
------ -
------------ ----------
------- ------------
----- ------------------------
------ -------------------------------
--
--
------ -
------------ ---- ---------
------- ------------
----------- --------------------------
------ ------------------------- ----------
-------- ----------------------------- ------- ------------
--
-
-
-
-
-
---查看 API 文档
完成了上面的工作后，我们就可以在浏览器中查看自动生成的 API 文档了。我们只需要访问以下 URL：
http://localhost:3000/documentation
在浏览器中打开这个 URL 后，就可以看到自动生成的 API 文档了。我们可以在文档中查看 API 的详细信息，包括请求和响应的参数、数据结构和描述信息等。
总结
在本文中，我们介绍了如何使用 hapi-swagger 插件来自动生成 API 文档。我们首先安装了 hapi-swagger 插件，然后在 Hapi.js 应用程序中配置了它。接着，我们使用 hapi-swagger 插件在 API 中添加了注释和元数据，来描述 API 的参数、响应和其他信息。最后，我们在浏览器中查看了自动生成的 API 文档。
使用 hapi-swagger 插件可以帮助我们更加方便地管理和维护 API 文档，提高开发效率和代码质量。如果你正在使用 Hapi.js 开发 Web 应用程序，那么 hapi-swagger 插件一定是一个不错的选择。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/657d1a2ad2f5e1655d7e63cf