前言
随着前后端分离的发展，Web API 已经成为现代 Web 应用和服务的基础架构之一。API 的设计和文档化变得越来越重要，因为它们决定了 API 的易用性和可维护性。
在 Node.js 和 JavaScript 界，Hapi 框架是一个颇受开发者喜爱的 Web 框架，它提供了丰富的插件系统，其中 Hapi-swagger 插件就是一个非常方便的工具，可以自动根据代码生成 API 文档。
在本文中，我们将介绍如何在 Hapi 应用中使用 Hapi-swagger 插件，并说明该插件的特性和配置，希望能对前端开发者有所帮助。
Hapi-swagger 插件简介
Hapi-swagger 插件是 Hapi 应用的一个插件，它提供了一个自动化的 API 文档生成工具，能够自动化地从代码的注释和路由信息中提取 API 文档，并生成一份基于 Swagger 规范（也称 OpenAPI 规范）的 API 文档。
Hapi-swagger 的主要特性如下：
- 自动生成 API 文档，避免手动书写文档的繁琐和错误；
- 支持 Swagger 规范 v2 和 v3，可以与其它 Swagger 工具集成；
- 使用基于注释的 API 文档注解，减少代码侵入性；
- 支持 API 身份验证和授权的配置。
使用 Hapi-swagger 插件
安装和引入
在 Hapi 应用中使用 Hapi-swagger 插件，需要先安装该插件：
npm install hapi-swagger
然后在应用中引入该插件：
-- -------------------- ---- -------
----- ----------- - ------------------------
----- -------------- - -
----- -
------ -------- --- ---------------
-------- -------
-
--
----- -----------------
-
------- ------------
-------- --------------
-
---
注意：上面代码中的 swaggerOptions 对象是一个配置选项，其中的 title 属性和 version 属性是必填项，分别表示 API 文档的标题和版本号。
注释 API 文档
在 Hapi 应用程序中注释 API 文档，可以使用 hapi-swagger 的注解格式，将 API 文档的所有信息都与 API 所属的函数或路由关联起来。通常，在定义路由处理程序时，我们会使用 hapi-swagger 提供的预定义 JSDoc 标签来注释 API 文档。例如：
-- -------------------- ---- -------
--------------
------- ------
----- --------------
-------- -
----- --------
------------ ---- - ---- -- ----
-------- ----- -------- --------- -- -
----- ---- - ----- ------------------------------
------ -----
--
--------- -
------- ------------
--- --------------------------------------------------- ----
--
--
--------- -
------- ------------
--- --------------------------------------------------- -----
----- ----------------------------------------- -------
------ -------------------------------------------------- ---------
--
-
-
---上面的代码中，我们使用 JSDoc 注解说明了以下 API 文档信息：
tags：API 的标签，可以用于分组和注释；description：API 的描述，概括 API 所做的事情；validate：API 的参数验证规则，使用了 Joi 的对象模式；response：API 的响应模式，使用了 Joi 的对象模式。
API 文档生成
在注释完 API 文档后，我们需要手动打开 Swagger UI，才能看到文档生成的效果。但是，Hapi-swagger 插件提供了一个基于路由的 Swagger endpoint，即 /documentation，可以自动将 API 的文档呈现在一个 Web 界面中。
打开浏览器，访问应用程序的 /documentation 路径，即可看到自动创建的 Swagger API 文档，如下图所示：
（图：Swagger UI 界面）
总结
Hapi-swagger 插件是一个快速、简洁地生成 API 文档的工具。在本文中，我们介绍了如何使用 Hapi-swagger 插件，在 Hapi 应用程序中注释和生成 API 文档。通过使用 Hapi-swagger 工具，我们可以快速而准确地将 API 文档和代码进行分离，提高 API 的可读性和可维护性，也让团队开发人员更好地理解每个 API 的功能和需求。
附：完整示例代码：
-- -------------------- ---- -------
----- ---- - ----------------
----- --- - ---------------
----- ----------- - ------------------------
----- ----- - -----------------
----- ------ - ------------------
----- ------ - ------------- ----- ---- ---
--------------
------- ------
----- --------------
-------- -
----- --------
------------ ---- - ---- -- ----
-------- ----- -------- --------- -- -
----- ---- - ----- ------------------------------
------ -----
--
--------- -
------- ------------
--- --------------------------------------------------- ----
--
--
--------- -
------- ------------
--- --------------------------------------------------- -----
----- ----------------------------------------- -------
------ -------------------------------------------------- ---------
--
-
-
---
----- -------- ------- -
----- -----------------
-------
------
-
------- ------------
-------- -
----- -
------ -------- --- ---------------
-------- -------
-
-
-
---
----- ---------------
------------------- ------- --- ---------------------
-
-------------------------------- ----- -- -
-----------------
----------------
---
--------来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/651be3de95b1f8cacd37da61