在开发前端应用程序时，创建和维护高质量的 API 文档非常重要，因为它们描述了如何与应用程序进行交互。为了简化这个过程，许多开发者使用 Swagger 工具来自动生成 API 文档。 Hapi 框架则提供了一个方便的方法来集成 Swagger，以便快速而准确地生成 API 文档。本文将介绍如何在 Hapi 项目中使用 Swagger。
第一步：安装 Swagger 软件包
在开始使用 Swagger 生成 API 文档之前，要确保已安装了 Hapi 和 Swagger 相应软件包。安装步骤如下：
npm i hapi-inert npm i hapi-vision npm i hapi-swagger
- hapi-inert：用于处理文件和静态资源的 Hapi 插件
- hapi-vision：用于处理 Hapi 应用程序视觉输出和视图引擎的插件
- hapi-swagger：Swagger 的 Hapi 插件
第二步：配置 Hapi API 服务器
创建 Hapi API 服务器前，只需安装并使用既定模块即可。
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - -----------------------
----- ------ - ------------------------
----- ----------- - ------------------------
----- ------ - -------------
----- -----
----- -----------
---
----- ---- - ----- -- -- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ---- ----
-------- -------
--
-------- ---------
------------------ -------
-
-
---
----- ---------------
------------------- ------- -- ---------------------
--
-------在上面的代码中，首先引入了 Hapi、Inert、Vision 以及 HapiSwagger。其中 HapiSwagger 被安装在 server.register 中。在初始化中，我们指定了接口信息，如文档标题和版本。也可以指定启用 Swagger 的协议（例如，http、https）。最后，使用 server.start 启动服务器。
第三步：为路由添加 Swagger 描述符
在路由定义中添加 swagger 描述符非常重要，这告诉 Swagger 如何生成文档。这里有两种方法来定义路由描述符：
方法一：添加描述符并控制响应
-- -------------------- ---- -------
--------------
------- ------
----- ----------------
-------- -
----- --------
------------ -------
------ ----- ---- ----
-------- --------- -- -- -
------ - -------- -------- --
--
-------- -
--------------- -
---------- -
------ -
------------ ------
------- ------------
-------- -----------------------
--
--
------ -
------------ -------
--
------ -
------------ ----------
-
-
-
-
-
---在这里，我们使用一个对象定义路由，并提供相关的描述符。这里使用的 tags、description 和 notes 描述符将在生成的 Swagger 文档中使用。handler 属性指出了该路由所需的处理程序函数。最后，在启用 Swagger 插件时，我们使用 plugins 属性添加路由的响应，以便 Swagger 的 schema 解析器能够确定响应格式。
方法二：使用 Joi objects 定义响应架构
-- -------------------- ---- -------
--------------
------- -------
----- ---------------------
-------- -
----- --------
------------ -------
------ ----- ---- ------- ---- ----
--------- -
-------- ------------
----- ------------------------
------ --------------------------------
--------- -----------------------
--
--
-------- --------- -- -- -
------ - -------- --------- --
--
-------- -
--------------- -
---------- -
------ -
------------ --------
------- ------------
-------- -----------------------
--
-
-
-
-
-
---使用 Joi 对象定义响应数据的优点是，它非常容易阅读和理解，并且再次突出了 Swagger 描述符的重要性。在这里，validate 描述符告诉 Swagger 应该如何验证包含在请求中的数据。最后，我们在启用路由的 Swagger 描述符时，定义了完成后应返回的 JSON 响应对象。
结论
通过使用 Hapi 和 Swagger，我们可以快速而准确地创建高质量的 API 文档，并使操作更加容易。在本教程中，我们介绍了如何集成 Swagger 到 Hapi 项目中，以及如何定义路由描述符和响应以生成 Swagger 文档。这些示例代码和说明可以帮助你快速开始使用 Swagger 和 Hapi 框架来生成 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/672c09e5ddd3a70eb6d44210