前言
作为一个前端开发人员，在与后端开发人员协作时，我们经常需要进行 API 文档的编写和维护。这是一个繁琐而重要的任务，因为 API 文档可以帮助我们更好地理解后端提供的接口，并且在我们需要开发前端应用时，也可以方便我们快速地构建应用。在这方面，hapi-swagger 是一个非常好用的工具，它可以帮助我们在 Hapi 中自动生成 API 文档。在本文中，我们将详细介绍如何使用 hapi-swagger 来生成 API 文档。
Hapi-swagger 简介
Hapi-swagger 是一个用于 Hapi 的插件，它可以帮助我们在 Hapi 应用程序中自动生成 Swagger / OpenAPI 文档。Swagger / OpenAPI 是一种基于 JSON 或 YAML 格式的 API 描述规范，它可以帮助我们通过定义接口的元数据来描述我们的 API。利用 Swagger / OpenAPI，我们可以在不需要访问实际代码的情况下生成 API 文档，这非常方便，因为我们不需要手动编写 API 文档。
由于 Hapi-swagger 基于 Swagger / OpenAPI，所以我们可以利用 Swagger UI 等工具，以可视化的方式查看 API 文档。同时，Swagger / OpenAPI 规范在很多开发工具中也得到了支持，如 Postman 等。
安装 hapi-swagger
在开始使用 hapi-swagger 之前，我们需要先安装它。我们可以通过 npm 包管理器来安装它：
$ npm install hapi-swagger
安装完成之后，在应用程序中引入它：
const HapiSwagger = require('hapi-swagger');
在 Hapi 中使用 hapi-swagger
下面我们来看一下如何在 Hapi 中使用 hapi-swagger。
首先，我们需要在 Hapi 应用程序中注册 hapi-swagger 插件。我们可以在 Hapi 的 server.register() 方法中进行注册。我们需要传入一些配置选项来告诉 hapi-swagger 如何生成 API 文档。
下面是一个完整的例子：
-- -------------------- ---- ------- ----- ---- - ---------------------- ----- ----------- - ------------------------ ----- ---- - --------------------- ----- ---- - ----- -- -- - ----- ------ - ------------- ----- ----- ----- ----------- --- ----- -------------- - - ----- - ------ ---------- -------- ------------- -- -- ----- ----------------- ----------------- ------------------ - ------- ------------ -------- -------------- - --- -------------- - ------- ------ ----- --------- -------- --------- -- -- - ------ ------- -------- -- -------- - ----- -------- ------------ ---- ------- ------ -------- - ----- --------- - - --- ----- --------------- ------------------- ------- --- --------------------- -- -------展开代码
在这个例子中，我们首先定义了一个 Hapi 服务器并指定其监听地址和端口。然后，我们定义了一个 swaggerOptions 配置对象，其中包括 API 文档的标题和版本号。接下来，我们通过 server.register() 方法来注册 hapi-swagger 插件，并传入 swaggerOptions 配置选项。在上述代码中，我们还定义了一个简单的路由 /hello，并通过在路由配置选项中设置 tags、description 和 notes 参数来告诉 hapi-swagger 插件如何生成 API 文档。
最后，我们使用 server.start() 方法来启动应用程序。如果启动成功，我们将看到控制台输出应用程序的监听地址和端口。
默认情况下，hapi-swagger 将使用 Joi 模块的描述对象来解析我们的路由配置选项，以生成 API 文档。如果我们要使用其他描述对象，可以在配置选项中设置 validatorUrl 属性来指定验证器 URL。
使用 hapi-swagger 生成 API 文档
现在，我们已经在 Hapi 中成功使用了 hapi-swagger 插件。接下来，我们将进一步介绍如何使用它来生成 API 文档。
我们可以通过访问 /documentation 路由来查看由 hapi-swagger 生成的 API 文档。例如，我们在 Hapi 应用程序中启动了服务并监听 3000 端口，那么我们可以在浏览器中输入 http://localhost:3000/documentation，就可以看到自动生成的 API 文档。
在下面的屏幕截图中，我们可以看到 hapi-swagger 生成的 API 文档样例。我们可以看到 API 文档是由多个部分组成的，包括概览、标签、路径和定义等。我们可以通过 Swagger UI 工具来查看这些文档，并与之交互。
在创建路由时，我们可以使用路由配置选项来指定每个路由的元数据。这些元数据可以帮助 hapi-swagger 自动生成 API 文档，包括标签、路径、操作、参数、请求体和响应体等。下面是一个完整的路由配置选项样例：
-- -------------------- ---- ------- - ------- ------- ----- ------------- -------- --------- -- -- - ------ - -------- ----- --------- -- -- -------- - ----- -------- ------------ ------- - --- ------ ------ ------- - --- ---- -- --- -------- -------- - --------------- - ---------- - ------ - ------------ ----- ------- -------------- ------- ------------ -------- ----------------------- -- -- ------ - ------------ -------- ------- ------- ------------ ----------- ------------------------------------- -------- ---------------------------------------- ------- -- - - - -- --------- - -------- ------------ ----- ----------------------------------------- ------- ------ ----------------------------------------- ------- -- -- --------- - ------- - -- ---- -------- ------ --- ---------- -------- ---- ------------ -------- ----------------------- -- - -- - -展开代码
在配置选项中我们可以指定多个参数来告诉 hapi-swagger 插件如何生成 API 文档。下面是一些最常用的参数：
- tags - 标签数组，将其用于函数的路由标记以在 Swagger UI 中组织和过滤方法。
- description - 描述路由的简短描述。
- notes - 提供有关路由的长描述和其他说明。
- validate - 指定 Joi 模板对象，用于验证和描述 payload、params、query 和 headers 实例数据模型。
- response - 关键描述服务可以响应客户端请求的期望输出。
- plugins - 为 hapi-swagger 定义一些特殊的规则，以控制文档生成的结果。
使用 hapi-swagger 生成的 API 文档在 Swagger UI 中呈现得非常清晰，并且可以与 Postman 等工具相集成。这使得 API 文档可以帮助我们更好地理解后端为我们提供的所有可用接口。同时，在前端开发过程中，我们可以使用 API 文档作为参考，更快地构建应用程序。
总结
在本文中，我们介绍了如何在 Hapi 中使用 hapi-swagger 插件来自动生成 API 文档。我们已经看到，hapi-swagger 是一个非常好用且易于使用的插件，它可以帮助我们更好地管理和维护我们的 API 文档。使用 hapi-swagger，我们可以大大提高前后端协作的效率，同时减少繁琐的手动编写 API 文档的过程。因此，在我们的前端开发过程中，使用 hapi-swagger 是非常必要的。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65b78486add4f0e0ff011923
