在前端开发中，API 文档是非常重要的一环。它不仅方便了前后端的沟通和协作，还能帮助团队更好地理解和使用接口。而 Swagger 是一款非常流行的 API 文档生成工具，它能够自动生成接口文档，并提供交互式的页面展示。本文将介绍如何在 Hapi.js 中引入 Swagger 自动生成 API 文档。
Hapi.js 简介
Hapi.js 是一个 Node.js 的 Web 框架，它提供了一系列的插件和工具，能够帮助我们快速构建 Web 应用程序。相比于 Express，Hapi.js 更加注重安全性和可扩展性。它的插件机制非常灵活，能够方便地扩展和定制功能。
Swagger 简介
Swagger 是一款开源的 API 文档生成工具，它能够自动生成接口文档，并提供交互式的页面展示。Swagger 可以通过注解或配置文件的方式生成接口文档，支持多种语言和框架，比较流行的有 Java 和 Node.js。
引入 Swagger 到 Hapi.js
在 Hapi.js 中引入 Swagger，需要借助两个插件：hapi-swagger 和 inert。前者是 Swagger 在 Hapi.js 中的实现，后者是 Hapi.js 的静态文件处理插件。
安装插件
首先，我们需要安装这两个插件：
npm install hapi-swagger inert
注册插件
在 Hapi.js 中使用插件，需要在服务器启动前进行注册。我们需要在 server.js 文件中引入 hapi-swagger 和 inert，并注册到服务器中。示例代码如下：
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - -----------------------
----- ------ - ------------------------
----- ----------- - ------------------------
----- ---- - --------------------------
----- ------ - -------------
----- -----
----- -----------
---
----- ---- - ----- -- -- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ---- ----
-------- ------------
-
-
-
---
----- ---------------
------------------- ------- -- ---------------------
--
-------------------------------- ----- -- -
-----------------
----------------
---
-------在上面的代码中，我们使用了 @hapi/inert 和 @hapi/vision 插件，它们是 hapi-swagger 的依赖项。HapiSwagger 是 hapi-swagger 的主要插件，我们需要将其作为一个对象传入到 server.register 方法中。其中，options 是可选的配置项，我们可以在这里设置 API 文档的标题和版本号等信息。
注册路由
接下来，我们需要在 Hapi.js 中注册路由，并添加 Swagger 的注解。Swagger 的注解包括 @swagger、@summary、@description、@param、@response 等。示例代码如下：
-- -------------------- ---- -------
--------------
------- ------
----- --------------------
-------- -
----- --------
------------ ---- ----- -- ---------
------ -------- - -------- ------- ---- --- ----- ------
--------- -
------- -
----- ----------------------------------------- -- --- ------ -- -------
-
--
-------- --------- -- -- -
----- ---- - --------------------
------ ------- ----------
--
-------- -
--------------- -
---------- -
------ -
------------ ----------
------- ---------------------------------------- -------- ---------
--
------ -
------------ ---- ---------
------- ------------
----------- ---------------------------------------- ----- ------ -------
------ ---------------------------------------- ----- ---------
--
-
-
-
-
-
---在上面的代码中，我们定义了一个路由 /api/hello/{name}，它接受一个参数 name。我们使用了 Joi 对参数进行了校验，并添加了 Swagger 的注解。其中，tags 是 API 文档中的标签，description 是接口的描述，notes 是接口的注释。validate 是参数的校验规则，handler 是接口的实现函数。最后，我们使用了 plugins 添加了 Swagger 的响应注解。
访问 API 文档
在启动服务器后，我们可以通过 http://localhost:3000/documentation 访问 Swagger 自动生成的 API 文档。在这个页面中，我们可以看到所有注册的路由和它们的详细信息，包括请求方法、请求路径、请求参数、响应状态码等。我们还可以在这个页面中测试接口，输入参数并发送请求，查看响应结果。这样，我们就能够方便地查看和测试接口了。
总结
在本文中，我们介绍了如何在 Hapi.js 中引入 Swagger 自动生成 API 文档。我们使用了 hapi-swagger 和 inert 两个插件，注册了路由并添加了 Swagger 的注解。最后，我们访问了 Swagger 自动生成的 API 文档，实现了接口的查看和测试。希望本文能够帮助你更好地使用 Hapi.js 和 Swagger。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/655ab6ddd2f5e1655d4ec55d