随着前端开发的发展，越来越多的项目需要使用到 API 接口，而 API 文档管理就变得尤为重要。Swagger 是一个流行的 API 文档管理工具，它可以帮助开发者设计、构建、描述和使用 RESTful API。本文将介绍如何在 Hapi 中使用 Swagger 进行 API 文档管理。
安装 Swagger
在 Hapi 项目中使用 Swagger 需要先安装 Swagger 插件。在终端中运行以下命令：
npm install hapi-swagger --save
配置 Swagger
安装完插件后，在 Hapi 的 server 中添加以下配置：
-- -------------------- ---- -------
----- ---- - ----------------
----- ----- - -----------------
----- ------ - ------------------
----- ----------- - ------------------------
----- ---- - ---------------------
----- ------ - --- --------------
-------------------
----- ------------
----- -----
---
----- ------- - -
------
-------
-
--------- ------------
-------- -
----- -
------ ---- ----
-------- -------------
--
--
--
--
------------------------ ----- -- -
-- ----- ----- ----
-------------------- -- -
-- ------- ----- ------
------------------- ------- --- ---------------------
---
---上述代码中的配置项包括：
- title：文档标题
- version：文档版本号
- host：API 服务的主机
- port：API 服务的端口号
除此之外，你还可以按照需要添加其他配置项，比如：
-- -------------------- ---- -------
-
--------- ------------
-------- -
----- -
------ ---- ----
-------- -------------
--
------------------ -------- -- ----------- --------------
-------------- -------------- -- ---------- --------- -----------
--------- ----------- -- --- -----
-------------------- - -- ------
---- -
----- ---------
----- ----------------
--- ---------
--
--
--
--编写 API 文档
在 Hapi 中，可以利用注释来生成 API 文档。Swagger 支持以下注释格式：
- @swagger.methodname(path)
- @swagger.path
- @swagger.summary
- @swagger.description
- @swagger.tag
- @swagger.parameter
- @swagger.response
- @swagger.security
- @deprecated
下面是一个使用了 Swagger 注释的 Hapi 路由示例：
-- -------------------- ---- -------
---
- --------
- -----------
- ----
- -----
- - -----
- ------------ ------ --- -----
- ---------
- - ----------------
- ----------
- ----
- ------------ -- ----- -- -----
- -------
- ----- ------------------------
--
--------------
------- ------
----- -------------
-------- --------- ------ -- -
----- ----- - -
- ------ ---- ------------- ----- -- --- -------- ------- -------- ------ --
- ------ ---- ------- -- --- ----- ------- ----- --------- --
--
------ -------------
--
---以上代码中，Swagger 注释包括路径、标签、描述、返回值等信息。可以使用 $ref 引用定义好的 models 或者 schemas。
在 Swagger UI 中查看文档
运行 Hapi 服务之后，访问 http://localhost:8080/documentation 就可以看到 Swagger UI：
Swagger UI 可以让开发者直观地查看 API 文档、测试 API 接口、调试等。
小结
本文介绍了如何在 Hapi 中使用 Swagger 进行 API 文档管理，通过安装和配置插件、编写 API 文档和在 Swagger UI 中查看文档等步骤，我们可以轻松地生成高质量的 API 文档。希望本文能够帮助想要使用 Swagger 进行 API 文档管理的开发者。
Source: FunTeaLearn,Please indicate the source for reprints https://funteas.com/post/677ff2c8ce7f48612525e672