在开发前端应用程序时，API 文档是不可或缺的一部分。它们提供了对应用程序中所有可用端点的全面文档，包括请求和响应的格式、参数、错误等。
手动编写 API 文档可能会很繁琐且容易出错。这就是为什么 Swagger 这样的自动化工具非常有用。Swagger 是一种开源的规范，可以自动生成 API 文档并提供一个交互式 UI，以便用户可以轻松地测试和探索 API。
在本文中，我们将介绍如何在 Hapi 框架中使用 Swagger 来自动生成 API 文档。
步骤 1：安装 Swagger 插件
首先，我们需要安装 Hapi Swagger 插件。该插件将在我们的应用程序中自动生成 Swagger 文档。
npm install hapi-swagger --save
步骤 2：配置 Swagger 插件
接下来，我们需要在我们的应用程序中配置 Swagger 插件。这可以通过在服务器启动之前使用 server.register 方法来完成。
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - -----------------------
----- ------ - ------------------------
----- ----------- - ------------------------
----- ------ - -------------
----- -----
----- -----------
---
----- ---- - ----- -- -- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ---- ---------------
-------- -----
-
-
-
---
---------------
------------------- ------- -- ---- -----------------
--
-------在上面的代码中，我们首先导入了必要的依赖项：@hapi/hapi、@hapi/inert、@hapi/vision 和 hapi-swagger。然后，我们创建了一个新的 Hapi 服务器并使用 server.register 方法注册了这些插件。
在注册 Hapi Swagger 插件时，我们可以通过 options 对象来配置文档的元数据。在这个例子中，我们设置了文档的标题和版本。
步骤 3：添加路由
现在我们已经配置了 Swagger 插件，我们需要添加一些路由来定义我们的 API 端点。这些路由应该包括所需的参数、请求和响应格式。我们还需要使用 Swagger 标记来指定每个路由的元数据。
下面是一个示例路由，用于在 Hapi 应用程序中创建新的用户：
-- -------------------- ---- -------
--------------
------- -------
----- ---------
-------- -
----- --------
------------ ------- - --- ------
------ -------- --- ----- ------- ---- --------
--------- -
-------- -
----- ------------------------
------ --------------------------------
--------- -----------------------
-
--
--------- -
------- ------------
--- ------------------------
----- ------------------------
------ -------------------------------
--
-
--
-------- --------- -- -- -
-- ------ - --- ---- --- ------ --- ---- ------
-
---在上面的代码中，我们使用 server.route 方法添加了一个新的路由。这个路由是一个 POST 请求，用于在 /users 端点上创建新的用户。
在路由的选项中，我们使用了几个 Swagger 标记。首先，我们使用 tags 标记将这个路由标记为 api。这将确保它显示在 Swagger UI 中的 API 文档中。
接下来，我们使用 description 和 notes 标记来描述这个路由的作用和预期的输出。
在 validate 标记中，我们定义了这个路由要求的有效载荷参数。在这个例子中，我们需要一个名为 name、一个名为 email 和一个名为 password 的字符串。
最后，在 response 标记中，我们定义了这个路由的预期响应格式。在这个例子中，我们期望响应包含一个 id、一个 name 和一个 email 字段。
步骤 4：查看生成的文档
现在我们已经定义了我们的路由和 Swagger 标记，我们可以启动我们的 Hapi 服务器并查看自动生成的 API 文档。
在本例中，我们可以在 http://localhost:3000/documentation 上访问 Swagger UI。这个页面显示了我们的 API 文档，并提供了一个交互式 UI，以便用户可以轻松地测试和探索 API。
结论
在本文中，我们介绍了如何在 Hapi 框架中使用 Swagger 来自动生成 API 文档。我们首先安装了 Hapi Swagger 插件，然后配置了它，然后添加了一些路由并使用 Swagger 标记来指定元数据。最后，我们启动了服务器并查看了我们的自动生成的 API 文档。
使用 Swagger 自动化工具可以大大简化 API 文档的编写过程，并确保文档与代码保持同步。在开发前端应用程序时，这是一个非常有用的工具，可以提高开发效率并减少错误。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/675be2b7a4d13391d8facce4