前言
在开发 Web 应用时，API 文档是不可或缺的一部分。API 文档可以帮助开发者理解 API 的功能和使用方法，也可以帮助团队协作和提高开发效率。Swagger 是一个流行的 API 文档生成工具，可以自动生成 API 文档并提供交互式的 UI 界面。
Hapi 是一个 Node.js 的 Web 框架，它的插件系统非常强大，可以支持各种各样的插件。在 Hapi 中，我们可以使用 swagger 插件来生成 Swagger API 文档。本文将介绍如何在 Hapi 中使用 swagger 插件生成 API 文档，并对一些常用的配置进行讲解。
安装 swagger 插件
在使用 swagger 插件之前，我们需要先安装它。可以使用 npm 进行安装：
npm install hapi-swagger --save
安装完成之后，我们需要在 Hapi 中注册 swagger 插件：
-- -------------------- ---- -------
----- ---- - ----------------
----- ----- - -----------------
----- ------ - ------------------
----- ----------- - ------------------------
----- ------ - --- -------------
----- -----
---
------ -- -- -
----- -----------------
------
-------
-
------- ------------
-------- -
----- -
------ --- -----
-------- --------
--
--
--
---
----- ---------------
------------------- ------- --- ---------------------
-----在上面的代码中，我们先引入了 Hapi、Inert、Vision 和 HapiSwagger 模块，然后创建了一个 Hapi 服务器实例。接着，我们使用 async/await 语法注册了 Inert、Vision 和 HapiSwagger 插件。在注册 HapiSwagger 插件时，我们可以传入一些配置，比如 API 的标题和版本号等。最后，我们启动了服务器并打印了它的地址。
生成 API 文档
在安装并注册了 swagger 插件之后，我们就可以生成 API 文档了。我们只需要在路由的配置中添加一些元数据，比如路由的描述、参数的类型和说明等，swagger 插件就会自动将这些信息转换成 Swagger API 文档。
-- -------------------- ---- -------
--------------
------- ------
----- ----------------
-------- -
------------ ---- ----- -- ---------
----- --------
--------- -
------- ------------
----- ------------------------
---
--
-------- --------- -- -- -
------ ------- -------------------------
--
--
---在上面的代码中，我们定义了一个 GET 请求的路由，它的路径是 /hello/{name}，其中 {name} 是一个参数。在路由的 options 中，我们指定了路由的描述、标签、参数的类型和说明等。其中，validate 字段使用了 Joi 模块来进行参数校验。最后，我们定义了一个处理函数，它会返回一句问候语。
启动服务器后，可以在浏览器中访问 http://localhost:3000/documentation，就可以看到自动生成的 API 文档了。
配置 Swagger 插件
除了上面介绍的基本配置之外，swagger 插件还提供了很多其他的配置选项。下面我们来介绍一些常用的配置。
接口前缀
有时候我们可能需要为 API 添加一个前缀，比如 /api，可以使用 routePrefix 选项来配置：
-- -------------------- ---- -------
-
------- ------------
-------- -
------------ ---------------------
----- -
------ --- -----
-------- --------
--
--
--上面的代码中，我们将路由的前缀设置为 /api/documentation。
文档格式
swagger 插件支持多种文档格式，比如 JSON、YAML 等。可以使用 documentationPage 选项来指定文档的格式和文件名：
-- -------------------- ---- -------
-
------- ------------
-------- -
------------------ -
------- -------
--------- ---------------
--
----- -
------ --- -----
-------- --------
--
--
--上面的代码中，我们将文档的格式设置为 YAML，并将文件名设置为 swagger.yaml。
安全认证
在实际开发中，我们可能需要对 API 进行安全认证。swagger 插件支持多种安全认证方式，比如 Basic 认证、OAuth2 等。可以使用 securityDefinitions 选项来配置安全认证方式：
-- -------------------- ---- -------
-
------- ------------
-------- -
-------------------- -
------ -
----- --------
------------ ------ ----------------
--
------- -
----- ---------
----- ----------
--- ---------
------------ ---- --- ----------------
--
------- -
----- ---------
----------------- --------------------------------------
--------- ----------------------------------
----- -----------
------- -
----- ----- --------
------ ------ --------
--
--
--
----- -
------ --- -----
-------- --------
--
--
--上面的代码中，我们定义了三种安全认证方式：Basic 认证、API Key 认证和 OAuth2 认证。在路由的 options 中，我们可以使用 security 字段来指定需要使用哪种安全认证方式：
-- -------------------- ---- -------
--------------
------- ------
----- ----------------
-------- -
------------ ---- ----- -- ---------
----- --------
----- -
----- -----------
----------- ----------
--
--------- -
------- ------------
----- ------------------------
---
--
-------- --------- -- -- -
------ ------- -------------------------
--
--
---上面的代码中，我们将路由的 auth 字段设置为 required，并指定了使用 Basic 认证。
总结
本文介绍了在 Hapi 框架中使用 swagger 插件生成 API 文档的方法，并讲解了一些常用的配置选项。通过使用 swagger 插件，我们可以快速、方便地生成 API 文档，并提高开发效率。当然，在实际开发中，我们还需要根据具体的需求对 swagger 插件进行更加细致的配置，以满足项目的需求。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65080c4095b1f8cacd335eba