在前端开发中，我们经常需要编写 API 文档，以便后端开发人员或其他前端开发人员能够理解和使用我们编写的 API。Swagger 是一种流行的 API 文档工具，它可以帮助我们生成易于阅读和使用的 API 文档。本文将介绍如何在 Hapi 项目中集成 Swagger，以便自动生成 API 文档。
安装 Swagger
首先，我们需要安装 Swagger。在 Node.js 中，我们可以使用 swagger-jsdoc 和 swagger-ui-express 这两个包来实现。swagger-jsdoc 可以帮助我们将 JSDoc 注释转换为 Swagger 规范的 JSON 文件，而 swagger-ui-express 则提供了一个 UI 界面，以便我们可以查看和测试生成的 API 文档。
我们可以使用以下命令来安装这两个包：
npm install --save-dev swagger-jsdoc swagger-ui-express
配置 Swagger
接下来，我们需要配置 Swagger。我们可以在 Hapi 项目的启动文件中添加以下代码：
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - -----------------------
----- ------ - ------------------------
----- ----------- - ------------------------
----- ---- - ---------------------
----- ------ - -------------
----- -----
----- -----------
---
----- ---- - ----- -- -- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ---- ---------------
-------- -------------
--
--
--
---
----- ---------------
------------------- ------- --- ---------------------
--
-------在这个例子中，我们使用 Hapi 的 Inert 和 Vision 插件来提供静态文件和模板渲染功能。我们还使用了 HapiSwagger 插件来集成 Swagger。在 options 中，我们可以设置一些 Swagger 配置，例如文档标题和版本号。
编写 Swagger 注释
现在我们已经配置好了 Swagger，接下来我们需要编写 Swagger 注释。我们可以在 API 路由处理程序中使用 JSDoc 注释来描述我们的 API。例如：
-- -------------------- ---- -------
---
- --------
- -------
- ----
- -------- --- - ---- -- -----
- ------------ ------- - ---- -- -----
- ----------
- ----
- ------------ - ---- -- -----
--
--------------
------- ------
----- ---------
-------- --------- -- -- -
----- ----- - -
- --- -- ----- ------- --
- --- -- ----- ----- --
- --- -- ----- --------- --
--
------ ------
--
---在这个例子中，我们使用 @swagger 标签来定义 API 的路径和方法。我们还可以在 @swagger 标签下使用其他标签来定义 API 的参数、请求体、响应等信息。例如：
-- -------------------- ---- -------
---
- --------
- ------------
- ----
- -------- --- - ---- -- --
- ------------ ------- - ---- -- --
- -----------
- - ----- --
- --- ----
- ------------ -- -- --- ---- -- ---
- --------- ----
- -------
- ----- -------
- ----------
- ----
- ------------ - ----
- --------
- -----------------
- -------
- ----- ---------------------------
- -----------
- --------
- -----
- ----- ------
- -----------
- ---
- ----- -------
- -----
- ----- ------
--
--------------
------- ------
----- --------------
-------- --------- -- -- -
----- -- - ------------------
----- ---- - - --- ----- ------- --
------ -----
--
---在这个例子中，我们使用 @swagger 标签来定义 API 的路径和方法，同时使用 parameters 标签来定义 API 的参数。我们还使用 content 标签来定义 API 的响应体，同时使用 components 标签来定义响应体中的 User 对象。
查看生成的 API 文档
现在我们已经完成了 Swagger 的配置和注释，接下来我们可以通过访问 http://localhost:3000/documentation 来查看生成的 API 文档。
在 Swagger UI 中，我们可以看到所有的 API 路径和方法，以及每个方法的参数、请求体、响应等信息。我们还可以在 Swagger UI 中进行测试，以确保我们的 API 能够正常工作。
总结
在本文中，我们介绍了如何在 Hapi 项目中集成 Swagger，以便自动生成 API 文档。我们首先安装了 swagger-jsdoc 和 swagger-ui-express 这两个包，然后配置了 Swagger 插件。接着，我们编写了 Swagger 注释来描述我们的 API，并最终查看了生成的 API 文档。希望本文能够对您在前端开发中使用 Swagger 有所帮助。
完整示例代码请参见我的 GitHub 仓库：https://github.com/CodingAssistant/hapi-swagger-example
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65cafb29add4f0e0ff4c7a63