在前端开发中，编写接口文档是必不可少的一个过程。而手动编写文档的方式往往费时费力，而且难免会出现遗漏或者不准确的情况。因此，使用基于 Hapi.js 的 Swagger UI 自动生成前后端接口文档是一个不错的选择。
介绍 Hapi.js
Hapi.js is an open-source and awesomely documented Node.js framework for developing web applications, including APIs, web services, and websites.
和 Express 不同，Hapi 拥有庞大的官方文档和翻译，涵盖了 API、插件、教程和其他相关话题。
Hapi.js 的请求生命周期被分为一系列有序事件，通过在请求处理过程中提供事件订阅和处理的方式，Hapi.js 可以很好地应对不同的请求类型和流程。
介绍 Swagger UI
Swagger UI 是一个基于 Swagger 规范的自动生成 API 文档的工具。通过 Swagger UI，我们可以使用 HTML、CSS 和 JavaScript 编写可交互的文档，可以根据输入输出模式自动生成负载的格式支持，并支持自定义主题和规范。
如何使用基于 Hapi.js 的 Swagger UI 自动生成前后端接口文档
安装 Hapi.js
我们首先需要在项目中安装 Hapi.js，可以使用 npm 来进行安装：
npm i -S hapi
安装 Swagger UI
接着，我们需要在项目中安装 Swagger UI，同样可以使用 npm 进行安装：
npm i -S swagger-ui
在项目中使用 Swagger UI
在安装了 Swagger UI 之后，我们就可以在项目中使用它了。
首先，在 Hapi.js 项目中引入 Swagger UI 的样式：
-- -------------------- ---- -------
--------------
------- ------
----- ---------------
-------- -
---------- -
----- ---------------------------------
-------- ------
------ -----
-
-
---然后，在同一文件中，我们需要构建一个用于存储 API 文档的 JSON 对象：
-- -------------------- ---- -------
----- ---- - ---------------------------
----- -------------- - -
----- -
------ ----- -----
-------- ------------
--
--------- ----
-------------- -------
--------- ------
--
----- ------ - --
------- ------
----- ----
-------- ----------------- ------ -
------------------- - ------ --------- ---
-
---
-------------- - - --------------- ------ --在上面的代码片段中，我们定义了一个 JSON 对象，存储了 API 文档的相关信息，包括项目的名称和版本号等。在构建完这个 JSON 对象之后，我们需要在路由中进行注册：
-- -------------------- ---- -------
-----------------
------- ------------------------
-------- --------------
-- ----- -- -
-- ----- -
-----------------
-------
-
---------------------
------------------ -- -
-- ----- -
-----------------
-
------------------- ------- --- -- --------------- ----
---
---自动生成 API 文档
构建完包含 API 文档信息的 JSON 对象之后，我们需要为所有的 API 添加 Swagger 规范标记，这样 Swagger UI 才能自动解释并显示 API 文档：
-- -------------------- ---- -------
--------------
------- ------
----- --------
-------- -
----- --------
------------ ---- --- ---- -------
------ ------- ------- --- -------
-------- --------- -- -- -
------ -----------------
-
-
---上面的代码片段中，我们添加了 Tags 和 Description，使得 Swagger UI 可以更容易地解释 API 文档。
最后，我们在浏览器中打开 Swagger UI，就可以看到自动生成的 API 文档了：
http://localhost:8000/documentation
示例代码
上述过程的示例代码可以在 GitHub 上找到：Swagger-Node.js
在使用这个示例代码之前，需要先安装 Node.js 和 npm。完成之后，再按照上述步骤安装 Hapi.js 和 Swagger UI，并按照上述代码进行配置即可。
总结
通过使用基于 Hapi.js 的 Swagger UI 自动生成前后端接口文档，我们可以大大降低编写文档的时间和成本，避免了因为遗漏或者不准确导致的问题。希望这篇文章能对大家在前端开发中自动生成 API 文档有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64660a62968c7c53b06b7d1b