在前后端分离的项目中,对于后端 API 接口文档的编写和说明显得至关重要。而 Swagger UI 是一个开源的 API 文档工具,它可以快速构建和调试 API 文档。本文将介绍如何使用 Hapi.js 和 Swagger UI 创建 API 文档并且使用它,让开发者更加高效的进行 API 的开发和维护。
Hapi.js 简介
Hapi.js 是一个现代化、安全、高性能的 Node.js Web 应用程序框架。它可用于构建单页应用程序、APIs 以及网站。该框架使用了一种插件化的方式以便于功能的扩展,同时它也是一个高度可定制的框架。
在接下来的实践中,我们将使用 Hapi.js 构建一个简单的 API,同时使用 Swagger UI 自动生产 API 文档。
安装与配置
安装 Hapi.js
在开始之前,我们需要确认已经安装了 Node.js 和 npm,我们可以使用以下命令来安装 Hapi.js:
--- ------- ----------
安装 Swagger UI
我们通过以下命令安装 Swagger UI:
--- ------- ------------------
配置 Hapi.js
我们来创建一个简单的 Hapi.js 服务器,接下来将添加一个 API 并使用 Swagger UI 为它生成 API 文档。首先,我们创建一个 index.js
文件并输入以下内容:
---- -------- ----- ---- - ---------------------- ----- --------- - ------------------------------ ----- ---- - ------------------ ----- ------ - ------------- ----- ----- ----- ----------- --- ----- ----- - ----- -- -- - -- -------- -------------- ------- ------ ----- --------- -------- --------- -- -- - ------ ------- -------- - --- -- ------- -- -- ----- --------------- - ---------------------------- ----------------- - ------- ---------------- -------- - --------------- - ---- --------------------- -- -- -- - ------- ---------------- -------- - ----------- --------------------- -- -- --- -- ----- ----- --------------- ------------------- ------- -- --------------------- -- --------
我们首先创建了一个 Hapi.js 服务器,并且注册了一个测试路由。接下来我们通过引入 yamljs
模块加载 Swagger YAML 文件,并注册 Swagger UI 插件。我们使用 await
启动服务器并在控制台显示运行端口。在此之前,我们需要创建一个 swagger.yaml
文件并输入以下内容:
-------- ----- ----- -------- ----- ------ ------- - ------- -- --- ------------ - ------ --- ----- ----- ------- - ------- ----- -------------- -------- - ---- --------- - ---------------- --------- - ---------------- ------ ------- ---- ------------ --------- - -------- -------- --------- - ---------------- ---------- ---- ------------ - -------- ------- -- --------- ------- ----- ------ ----------- -------- ----- ------ -------- ------ ------
这里我们定义了一个简单的 API,其中包含了一个 GET
方法用于从 /hello
路径获取一条问候语。Swagger UI 将会在这个文件基础上生成相应的 API 文档。
注:本示例所生成的 API 文档在本机 3000 端口内运行,请确保此端口没有被占用。
使用 Swagger UI
我们现在可以运行这个服务器,并在浏览器中打开 http://localhost:3000/api-docs
来查看 Swagger UI 编制的 API 文档。Swagger UI 将在 URL /api/documentation
下生成 API 文档。这是上面配置文件中 Swagger UI 的相关配置代码部分(很重要):
----- --------------- - ---------------------------- ----------------- - ------- ---------------- -------- - --------------- - ---- --------------------- -- -- -- - ------- ---------------- -------- - ----------- --------------------- -- -- ---
这里我们利用了 Hapi.js 插件机制,并将 Swagger UI 注册为插件。同时,我们设置了 swaggerDocument
使用 YAML 文件的内容,并将 URL:/api/documentation
传递给 Swagger UI 进行相关配置。
下面是 Swagger UI 的截屏:
如图,我们可以很清晰地看到我们在 swagger.yaml
文件中定义的 API 文档。而且 Swagger UI 还提供了一个交互式的测试页面,使我们可以轻松地测试我们的 API,同时可以展示我们所注册的 API 描述信息。
结论
在本文中,我演示了如何使用 Hapi.js 和 Swagger UI 快速构建和测试 API 接口,并自动生成 API 文档。这使我们能够更迅速地开发和测试 API 接口,并提高开发效率。同时,Swagger UI 可以为我们的项目提供更好的文档和可读性。如果您有相关项目的需求,我相信本文能够给您提供很好的帮助指导。
来源:JavaScript中文网 ,转载请注明来源 本文地址:https://www.javascriptcn.com/post/6708db5ad91dce0dc874c173