如果你是一位前端开发人员，你肯定会遇到过这样的问题：当你创建一个 API 时，你需要手动编写 API 文档，然后更新这些文档。这是一项相当繁琐的任务，而且容易出现错误。
Hapi 和 Swagger 是两个开源的工具，它们可以帮助你自动创建 API 文档。在本文中，我将向你展示如何将它们结合起来，从而为你的 API 创建自动生成文档。
Hapi 是什么？
Hapi 是一个 Node.js 开发框架，它由 Walmart 创建并开源，用于创建 Web 应用程序和 API。Hapi 有一个强大的插件系统，它允许开发人员轻松地扩展应用程序的功能。
下面是一个简单的 Hapi 应用程序：
-- -------------------- ---- ------- ----- ---- - ---------------- ----- ------ - --- ------------- ----- ---- --- -------------- ------- ------ ----- --------- -------- --------- -- -- - ------ ------ ------- - --- ---------------------- -- - ------------------- ------- --- --------------------- ---展开代码
在这个例子中，我们创建了一个简单的 Hapi 应用程序，它监听 3000 端口，并定义了一个路由，当用户请求 /hello 时，它返回一个简单的字符串：“Hello world”。
Swagger 是什么？
Swagger 是一个 API 规范和工具集，它的目标是帮助开发人员和企业设计和构建更好的 API。Swagger 具有许多功能，其中最常见的是生成 API 文档。
Swagger 文档的一个很好的例子是它的在线编辑器。当你在编辑器中定义一个 API 时，它会自动生成文档，以帮助你更好地了解 API。
如何为 Hapi 创建 API 文档
我们将使用 Swagger 帮助我们自动创建 Hapi 的 API 文档。为此，我们需要安装 swagger 和 Hapi-swagger 插件。
npm install swagger hapi-swagger --save
在我们安装了这些依赖项之后，我们需要对我们的应用程序进行一些修改，以便添加 Swagger。
-- -------------------- ---- ------- ----- ---- - ---------------- ----- ----- - ----------------- -- -------- ----- ------ - ------------------ -- -------- ----- ----------- - ------------------------ ----- ------ - --- ------------- ----- ---- --- ----- -------------- - - ----- - ------ ----- --- --------------- -------- ------- - -- ----- ------------- - - ------ ------- - ------- ------------ -------- -------------- - -- -------------------------------------- -- - -------------- ------- ------ ----- --------- -------- --------- -- -- - ------ ------ ------- -- -------- - ----- -------- ------------ ---- ------- ------ ---- --- --- ----- -- ---- --------- --------- -- - --- ---------------------- -- - ------------------- ------- --- --------------------- --- ---展开代码
在这个例子中，我们添加了一些新的依赖项 Inert 和 Vision，这些是 Swagger 所需的。我们还定义了 swaggerOptions 对象，它允许我们定义一些 Swagger 的元数据，例如标题和版本。
在 pluginOptions 数组中，我们添加了 Hapi-swagger 插件，并将 swaggerOptions 作为选项传递。
最后，我们使用 options 对象定义了我们的路由。这个对象包含一些元数据，例如标签、描述和笔记。这些元数据将帮助 Swagger 自动生成文档。
参数校验
Swagger 可以自动根据路由参数定义自动生成参数校验文档，开发者只需要在 route.metho.options 配置 validate 参数即可，示例代码如下：
-- -------------------- ---- ------- -------------- ------- ------- ----- ---- -------- --------- -- -- - ----- - ----- --- - - ---------------- ----- ----- - ------- --------- ----- ---- - ---- --- ------ ----- ----- ------ ---------- ---------- - -------- - ----- -------- ------------ ---- ----- ---- ---- ------------- ------ ---- --- --- ----- -- ---- ------- ---- ---- --- ----- --------- - -------- - ----- ----------------------------------------- ------- ---- --------------------------------------------------------- ----- - - - ---展开代码
其中，我们在 validate 参数中传入 payload 对象，对象中存放了两个参数 name 和 age 的校验条件。
总结
Hapi 和 Swagger 是两个强大的工具，它们可以帮助你更轻松地创建 Web 应用程序和 API，并自动生成文档。在本文中，我们学习了如何将它们结合起来创建自动生成文档的 API。使用 Hapi 和 Swagger，你可以将更多的时间用于编写代码，而非手动编写文档。
完整源码请查看这个 GitHub repo。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65026e6195b1f8cacdfb8676
