在前后端分离的项目中，API 接口文档的编写是很重要的一部分。Swagger 是一个可以帮助我们编写并维护 API 接口文档的开源工具。在 Hapi 框架中，我们可以使用 Swagger 来开发 API 接口文档。
什么是 Swagger
Swagger 是一个用于设计、构建、记录和使用 RESTful API 的开源工具。它包含了一个规范和完整的框架，用于生成、搭建和可视化 RESTful API 的接口文档。通过 Swagger，我们可以方便地定义和管理 API 的参数、请求体、响应体等信息，也可以轻松地调试和测试不同的 API 接口。
如何在 Hapi 中使用 Swagger
在 Hapi 中使用 Swagger，我们需要借助一个名为 hapi-swagger 的插件。这个插件是 Swagger 的 Hapi 实现，并且可以在 Hapi 应用程序中自动生成 API 文档。
安装插件
首先，我们需要使用 npm 安装 hapi-swagger 插件。
npm install hapi-swagger -S
导入插件
在 Hapi 应用程序中，我们需要从 hapi-swagger 中导入 register 函数，然后将其注册到 Hapi 实例中。
-- -------------------- ---- -------
----- ---- - ----------------------
----- ----- - -----------------------
----- ------ - ------------------------
----- ----------- - ------------------------
----- ------ - -------------
----- -----
----- -----------
---
----- ---- - ----- -- -- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ ---- ---------------
-------- -------
-
-
-
---
-- ------------
--------------
------- ------
----- ---------
-------- --------- -- -- -
------ ------ --------
-
---
----- ---------------
------------------- ------- -- ---------------------
--
-------在上面的代码中，我们从 hapi-swagger 模块中导入 register 函数，并将其作为一个插件来注册到 Hapi 实例中。register 函数接收一个对象作为参数，其中的 options 属性用于配置 Swagger 的一些基本信息，例如文档的标题和版本号等。
编写 Swagger 注解
在 Hapi 路由处理程序的注释中，我们可以使用 Swagger 注解来定义 API 的参数、请求体、响应体等信息。下面是一些常用的 Swagger 注解：
| 注解 | 说明 |
|---|---|
@swagger |
用于标记路由处理程序是否需要生成文档 |
@summary |
简要描述路由处理程序的作用 |
@description |
对路由处理程序做更详细的描述 |
@tag |
将路由处理程序分组到指定的标签下 |
@queryParam |
定义请求 URL 中的查询参数 |
@pathParam |
定义请求 URL 中的路径参数 |
@header |
定义请求头信息 |
@body |
定义请求体的 JSON Schema |
@response |
定义响应体的 JSON Schema |
下面是一个使用 Swagger 注解来定义路由处理程序的例子：
-- -------------------- ---- -------
--------------
------- ------
----- --------------
-------- -
----- --------
-------- ----- --------- -- -- -
----- -- - ------------------
----- ---- - ----- ------------------
-- ------- -
------ -----------------------
-
------ --------------
--
------------ ---- ---- -- ----
------ ---------- ---- ------ ---- --- -------- ----- -- -----
--------- -
------- ------------
--- ----------------------------------------- ----
--
--
--------- -
------- ------------
--- -------------
----- -------------
------ ------------
--
-
-
---在上面的例子中，我们使用 options 属性定义了路由处理程序的一些额外信息，例如：标签、描述、注释、参数校验规则和响应体的 JSON Schema 等。
查看 Swagger 文档
注册了 hapi-swagger 插件之后，我们可以在浏览器中访问 Swagger 文档页面。默认情况下，Swagger 文档的地址是 http://[host]:[port]/documentation，例如：http://localhost:3000/documentation。
在这个页面中，我们可以查看所有已经定义的路由及其相关信息，例如请求 URL、请求方法、请求参数等，还可以通过“Try it out”按钮测试 API 接口的调用效果。
总结
使用 Swagger，我们可以方便地编写和维护 API 接口文档，提高开发效率和代码质量。在 Hapi 框架中，使用 hapi-swagger 插件可以轻松地集成 Swagger，并自动生成 API 文档。在编写路由处理程序时，我们应该使用 Swagger 注解来描述参数、请求体、响应体等信息，以免忘记或遗漏关键信息。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/646c16b1968c7c53b0b25b04