在开发 Web 应用时，为了保证代码的可维护性和可扩展性，常常需要提供完善的 API 文档。而手工编写 API 文档往往需要耗费大量的时间和精力，而且容易出现漏写或过时的情况。因此，使用工具自动生成 API 文档是非常必要的，特别是在中大型 Web 应用中。
如果你是使用 Node.js 进行 Web 开发的开发者，那么 Hapi.js 及其插件 hapi-swagger 就是你生成 API 文档的最佳选择。Hapi.js 是一个构建 Web 应用和服务的框架，而 hapi-swagger 则是 Hapi.js 的一个插件，它可以方便地生成符合 Swagger 2.0 规范的 API 文档。本文就将详细介绍如何使用 hapi-swagger 进行 API 文档生成。
安装和配置
要使用 hapi-swagger 进行 API 文档生成，首先需要在你的 Node.js 项目中安装 hapi 和 hapi-swagger 两个依赖库：
$ npm install hapi hapi-swagger
接下来，在你的 Hapi.js 项目中引入 hapi 和 hapi-swagger 并进行基本配置。下面是一个基本的示例代码：
-- -------------------- ---- -------
----- ---- - ----------------
----- ----- - -----------------
----- ------ - ------------------
----- ----------- - ------------------------
----- ---- - ---------------------
-- ------------
----- ------ - -------------
----- -----
----- ------------
----- -
------ ----------
-------- -------------
------------ ----------------
-
---
-- -- ----- - ------ --
-----------------
------
-------
-
------- ------------
-------- -
----- -
------ --- --- ----
------------ --- ------------ ------
-------- ------------
-
-
-
-- ----- -- -
-- ----- -
----- ----
-
-- ----
--------------
-
------- ------
----- ----
-------- --------- -- -- -
------ - -------- ------- ------- --
--
-------- -
--- --------
------------ --- ------ -------
-
-
---
-- -----
------------------ -- -
-- ----- -
----- ----
-
------------------- ------- --- ---------------------
---
---在上述示例代码中，我们定义了一个 Hapi.js 服务器，并且使用 inert 和 vision 这两个插件。其中 inert 插件可以用来处理静态文件，而 vision 插件则用于模板渲染。此外，我们还使用了 HapiSwagger 插件，并在其 options 中定义了 API 文档的基本信息。其中 Pack 变量指向了项目的 package.json 文件，可以用来获取项目的名称、版本号和描述等信息。
定义路由和 API 文档
了解了基本概念和配置后，就可以开始定义路由和 API 文档了。首先，我们需要在路由定义中添加 options 对象，并在其中添加一些 API 文档中需要展示的元素，例如 id、description、notes、tags 等。下面是一个示例代码：
-- -------------------- ---- -------
--------------
-
------- ------
----- ----
-------- --------- -- -- -
------ - -------- ------- ------- --
--
-------- -
--- --------
------------ --- ------ --------
------ -
----------
----------
--
----- -------
-
-
---上述示例代码中，我们在 options 对象中添加了一些 API 文档需要展示的元素。其中 id 是这个路由的唯一标识符，description 是对这个路由的简短描述，notes 则可以添加一些详细的说明，tags 则用于对不同类型的 API 进行分类。
接下来，我们需要在服务器启动时启用 hapi-swagger 插件。这个插件的主要作用是将定义好的路由自动转换成符合 Swagger 2.0 规范的文档。此外，该插件还提供了一个 API 文档查看器，可以用于展示生成的 API 文档。要启用该插件，只需要将其作为 server.register() 方法的第三个参数传入即可。下面是一个示例代码：
-- -------------------- ---- -------
-----------------
------
-------
-
------- ------------
-------- -
----- -
------ --- --- ----
------------ --- ------------ ------
-------- ------------
-
-
-
-- ----- -- -
-- ----- -
----- ----
-
-- -------
---在上述示例代码中，我们将 HapiSwagger 插件作为 server.register() 方法的第三个参数传入，并在其 options 对象中定义了 API 文档的基本信息，包括 title、description 和 version。
最后，使用浏览器访问 http://localhost:3000/documentation 即可查看生成的 API 文档。你会发现，hapi-swagger 插件已经根据定义好的路由自动生成了符合 Swagger 2.0 规范的文档，包括每个路由的基本信息、请求参数、响应结果等。同时，该插件提供了方便的搜索功能，可以快速找到指定 API 的信息。下面是 API 文档查看器的截图：
总结
本文介绍了如何使用 Hapi.js 的 hapi-swagger 插件进行 API 文档生成。从安装和配置到路由和 API 文档定义，详细地介绍了使用 hapi-swagger 进行 API 文档生成的全部流程。希望通过本文的介绍，读者可以更好地使用 hapi-swagger 插件，并生成规范、完善的 API 文档，为 Web 开发带来更高效和便捷的体验。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/649d0bd648841e98949c2c5b