在开发 Web 应用程序时，编写清晰的 API 文档是至关重要的，因为它可以让其他开发人员了解你的代码并简化项目的维护。Hapi.js 是一个面向企业级的 Node.js 框架，它提供了强大而灵活的 API 文档生成器，可以帮助我们轻松地编写和维护 API 文档。
安装 Hapi-swagger
Hapi-swagger 是 Hapi.js API 文档生成器的一个插件。它能够自动生成 API 文档，还可以用于在 UI 中浏览文档。让我们通过 npm 全局安装该插件:
npm install hapi-swagger –save
基本用法
现在我们已经安装了 hapi-swagger 插件，下一步是将它添加到我们的项目中。配置很简单，我们先来看一下最简单的用法：
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - -----------------------
----- ------ - ------------------------
----- ----------- - ------------------------
----- ---- - ---------------------
----- ---- - ----- -- -- -
----- ------ - -------------
----- -----
----- -----------
---
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ---- ---------------
-------- -------------
--
-
-
---
----- ---------------
------------------- ------- -- ---- -----------------
--
-------在这个例子中，我们将插件注册为服务器插件，并将其与必需的 inert 和 vision 插件一起注册。options 对象用于配置文档页面的一些信息，例如标题和版本号。我们可以通过 http://localhost:3000/documentation 访问生成的文档页面。
默认情况下，hapi-swagger 插件是为每个路由自动生成 API 文档的，当应用程序重启时，它将重新生成文档。此外，Swagger UI 将不需要任何配置即可与 hapi-swagger 无缝交互。
更高级的用法
统一配置生成文档
我们可以为特定的路由指定其他 Swagger 配置，例如请求的查询参数和响应体。这很有用，因为不同的路由可能需要不同的 Swagger 配置。
-- -------------------- ---- -------
--------------
------- ------
----- ---------
-------- ------------
-------- -
----- --------
------------ ---- -------
------ -------- - ---- -- -------
--------- -
------ ------------
------ --------------------------------------------------
------- ----------------------------------------
---
----------- --------- -- ---- -- -
----- ----
-
--
--------- -
------- ---------------
-
-
---在这个例子中，我们通过 options 对象为路由指定了许多 Swagger 配置，例如路由的说明、查询参数、错误处理和响应架构定义。这些配置将显示在自动生成的文档中。
Swagger @tags
Swagger @tags 标签是 Swagger 规范的一部分，可以让我们在 API 文档中将路由划分到不同的组中。这可以让用户更轻松地在文档中浏览和搜索。
-- -------------------- ---- -------
--------------
------- ------
----- --------------
-------- ------------
-------- -
----- ------- ---------
------------ ---- ---- -- ----
------ -------- - ---- -- ----
--------- -
------- ------------
--- -----------------------
--
--
--------- -
------- -----------------
-
-
---在这个例子中，我们通过在 @tags 标签中传递一个字符串数组来指定我们的路由属于多个 tag。这将使文档更加整洁和易于使用。
结论
在这篇文章中，我们学习了如何在 Hapi.js 中生成 API 文档。我们使用了 hapi-swagger 插件，这是一种方便而强大的 API 文档生成器。我们已经了解了如何在服务器级别和路由级别配置 Swagger，以便于为我们的 API 提供更详细的文档。
现在您可以更好地管理和维护您的 API 服务，并向其他人展示您的 API 功能。如果您有任何问题或疑问，请查看 hapi-swagger 的文档并提出问题。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/673316870bc820c58240753e