前言
Hapi 是一个开源的 Node.js web 应用框架,它提供了可靠的服务端基础架构,以便构建可扩展的应用程序。Swagger 是一个流行的 API 文档生成工具,能够帮助我们轻松地创建、维护和分享 API 文档。今天,我们将了解如何在 Hapi 中使用 Swagger,以支持 REST 请求。
什么是 Swagger
Swagger 是一个基于 OpenAPI 规范的 API 生成工具,它可以自动生成代码和文档,从而可大大简化开发人员的工作。Swagger 的主要目的是提供高质量的 API 文档和交互式文档,以帮助开发人员快速了解 API 接口的功能。Swagger 可以生成以下内容:
- 可视化 API 文档
- 请求和响应模式
- 错误消息和验证
- API 客户端 SDK
- API 服务器桩程序
在 Hapi 中使用 Swagger
Hapi 提供了一个插件 - hapi-swagger,它能让我们轻松地将 Swagger 集成到 Hapi 应用程序中,使得自动生成 API 文档变得非常容易。
安装 hapi-swagger 插件
首先,我们需要安装 npm 包 hapi-swagger 和 joi,然后将插件引入到 Hapi 应用程序:
npm install hapi-swagger@9 joi
-- -------------------- ---- ------- ----- ---- - ---------------- ----- ----- - ----------------- ----- ------ - ------------------ ----- ----------- - ------------------------ ----- ---- - --------------------- ----- ------ - --- ------------- ----- ----- ----- ------------ --- ----- ---- - ----- -- -- - ----- -------------- - - ----- - ------ ----- --- --------------- -------- ------------- -- -- ----- ----------------- ------ ------- - ------- ------------ -------- --------------- -- --- ----- --------------- ------------------- ------- --- --------------------- -- -------
在以上代码中,我们引入了 Inert、Vision 和 HapiSwagger 插件,其中 Inert 和 Vision 是 Hapi 的核心插件,HapiSwagger 是用于添加 Swagger 文档生成的插件。我们还定义了 SwaggerOptions,它定义了我们的 API 的基本信息,例如标题、版本等。
配置路由
接下来,我们需要为路由配置 Swagger 文档。我们可以通过将 joi 规范嵌入到 Hapi 的路由选项中,以便为 API 文档添加其他详细信息。
-- -------------------- ---- ------- -------------- ------- ------ ----- ---------------- -------- -------- --------- -- - ------ ------ ------------------------- -- -------- - ----- -------- ------------ ---- ----- -- --------- --------- - ------- - ----- ------------ ----------- ----------------- ---- -- --- ------ -- ------- - - - ---
在上述代码中,我们定义了一个 GET 请求路由,以接受一个名字参数。我们使用 joi 对参数进行校验,以确保它是字符串,并添加了描述信息。
生成 Swagger 文档
我们使用 generateSwaggerEndpoint 选项来生成 swagger 文档的 JSON。
-- -------------------- ---- ------- ----- -------------- - - ----- - ------ ----- --- --------------- -------- ------------- -- -------------------- - ---- - ----- --------- ----- ---------------- --- -------- - -- --------- -- ---- -- --- ----- - - ----- ------ ------------ ---- ---------- - -- -------- --------- ----- ---------------- -- ----- --------- - -------------------------- ----- ----- - ----------------- ----- ------ - ------------------ ----- --------------- - ----------------------------- ----------------------- ------- - --------- ---------- -------- - ----- - ------ ----- --- --------------- -------- ------------- - -- -- - --------- ---------------- -------- - ------ ---- ------ ----- -------- -------------- - ------ ---------------- ------ --------- ------------ ------ ---- ----- -------- -- -------------- - --- -------- ----- - -- ----- - ----------------- - --- -- ---------------- - ------------------ -- - -- ----- - -------------------- -------- ------- -- ---- --------------- - ------------------- ------- --- -------------------- -- - -------------- - -------
现在,我们可以使用 Swagger UI 界面来查看我们的 API 文档。只需打开浏览器并访问 http://localhost:3000/docs,即可查看所有可用的端点。我们可以点击一个请求端点以查看更多详细信息。默认情况下,Swagger UI 会显示所有参数和结果,以及支持所有 HTTP 动词。
结论
使用 hapi-swagger 插件轻松地将 Swagger 集成到 Hapi 应用程序中,自动生成详细 API 文档。Swagger 能够帮助我们快速了解 API 接口的功能,从而更容易地构建可扩展的应用程序。
希望这篇文章对你有所帮助!
来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/674ecd14e884a3e30f2a165e