在前端开发中，编写 API 文档是必不可少的一个环节。而使用 Hapi 和 Swagger 可以方便地创建并维护 API 文档，本文将介绍如何使用这两个工具来编写高效、规范的 API 文档。
什么是 Hapi？
Hapi 是一款 Node.js 的框架，它提供了一种建立可维护和可扩展应用程序的方式。Hapi 的核心特点是强大的路由系统和插件机制，可以让我们更加方便地管理和开发应用程序。Hapi 也是目前 Node.js 生态中最受欢迎的框架之一。
什么是 Swagger？
Swagger 是一款基于 OpenAPI 规范的 API 文档生成工具。它可以将 API 的定义转换成可交互的文档，使得开发者可以更加方便地了解和使用 API。
配置 Hapi 和 Swagger
首先我们需要安装 Hapi 和 Swagger：
npm install hapi swagger
然后在项目的根目录下创建一个 server.js 文件，输入以下代码：
-- -------------------- ---- -------
----- ---- - ----------------
----- ----- - -----------------
----- ------ - ------------------
----- ----------- - ------------------------
----- ---- - ---------------------
----- ------ - --- --------------
-------------------
----- ------------
----- ---------------- -- -----
---
----- ------- - -
----- -
------ ---- ----
-------- -------------
--
--------- ----
------------------ -----------------
--
-----------------
------
-------
-
--------- ------------
--------
--
-- ----- -- -
-- ----- -
------------------ --- -----
----- ----
-
---
------------------ -- -
-- ----- -
------------------ --- -----
----- ----
-
------------------- ------- --- ---------------------
---这是一个简单的 Hapi 服务器，也带有一个 Swagger 的配置项。我们需要将 Swagger 的配置项通过 hapi-swagger 插件加载到 Hapi 中。其中 Inert 和 Vision 是 Hapi 的插件，它们提供了静态文件引用和模板渲染的功能。
在 options 中，我们可以做出以下的配置：
info：API 文档的基本信息。basePath：API 的基础路径。documentationPath：API 文档的路径。
在配置好后，我们就可以执行 npm start 来启动我们的服务器啦。
编写 API 文档
接下来，我们需要在 Hapi 中定义 API，以及在 Swagger 中描述 API。我们可以在路由文件中定义 Hapi 的路由，然后使用 Swagger 的注解来描述 API 的信息。
比如，我们在 server.js 文件中定义一个 /hello 接口：
server.route({
method: 'GET',
path: '/hello',
handler: (request, reply) => {
reply('Hello, world!');
},
});然后在接口的定义处，我们使用 Swagger 的注解来描述 API：
-- -------------------- ---- -------
--------------
------- ------
----- ---------
------- -
----- --------
------------ ---- ----- -- --- -------
------ -------- - ----- ---------
-------- --------- ------ -- -
------------- ---------
--
-------- -
--------------- -
---------- -
------ -
------------ ----------
------- ------------------------
--
--
--
--
--
---其中的注解包括：
tags：API 分类信息，例如api。description：API 的描述信息。notes：API 的备注信息。handler：API 的处理函数。plugins：插件配置，其中的hapi-swagger指定 Swagger 的配置。
在 responses 中，我们描述了 API 的响应信息，在这个例子中只有一个 200 成功响应，返回一段字符串。Swagger 支持更多的内容描述，例如参数、Model 等等。大家可以根据自己的需要进行定义。
查看 API 文档
接下来，我们在浏览器中访问 localhost:3000/documentation 就可以看到 Swagger 自动生成的 API 文档啦。通过 Swagger，我们可以方便地查看每个 API 的描述和响应信息，并且进行测试。
总结
使用 Hapi 和 Swagger，我们可以方便地创建和维护高效、规范的 API 文档。Hapi 的路由和插件机制非常方便，可以让我们更加灵活地管理和开发应用程序。而 Swagger 的 OpenAPI 规范也使得 API 更加可靠和可测试。
希望这篇文章能对你有所帮助，也欢迎大家来尝试使用 Hapi 和 Swagger 来编写自己的 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64759a4a968c7c53b029e2c1