Swagger 是一套定义 RESTful API 规范的工具，可以方便地生成 API 文档。在使用 Hapi 框架开发 RESTful API 时，如果能够集成 Swagger，将大大方便 API 使用者的调试和文档查看。本文将介绍如何在 Hapi 框架中集成 Swagger。
准备工作
在开始集成 Swagger 之前，我们需要完成以下几个准备工作：
- 安装 Hapi 框架及相关插件
npm install hapi @hapi/inert @hapi/vision hapi-swagger
其中，@hapi/inert 和 @hapi/vision 是 Hapi 框架的基础插件，用于处理静态文件和视图。hapi-swagger 插件则用于集成 Swagger。
- 编写 API 接口
在本文中，我们将以 Hapi 官网上的一个示例为例：
-- -------------------- ---- ------- ----- ---- - ---------------------- ----- ---- - ----- -- -- - ----- ------ - ------------- ----- ----- ----- ----------- --- -------------- ------- ------ ----- --------- -------- --------- -- -- - ------ ------ -------- - --- ----- --------------- ------------------- ------- -- ---- ----------------- -- -------------------------------- ----- -- - ----------------- ---------------- --- -------展开代码
我们定义了一个简单的 GET 请求 /hello，返回字符串 Hello World!。
集成 Swagger
- 注册插件
首先，我们需要在 init 函数中注册插件：
-- -------------------- ---- ------- ----- ---- - ---------------------- ----- ----- - ----------------------- ----- ------ - ------------------------ ----- ----------- - ------------------------ ----- ---- - --------------------- ----- ---- - ----- -- -- - ----- ------ - ------------- ----- ----- ----- ----------- --- ----- -------------- - - ----- - ------ ----- --- --------------- -------- ------------- -- -- ----- ----------------- ------ ------- - ------- ------------ -------- -------------- - --- -------------- ------- ------ ----- --------- -------- --------- -- -- - ------ ------ -------- -- -------- - ----- -------- ------------ ----- ----- ----- ------ -------- ----- --------- -------- - --------------- - ---------- - ------ - -------------- ---------- --------- ------------ -- ------ - -------------- ---- --------- --------- ------------------- ----------- ------------------------ ------ ------------------------ -------- ----------------------- ----------------- - - - - - --- ----- --------------- ------------------- ------- -- ---- ----------------- -- -------------------------------- ----- -- - ----------------- ---------------- --- -------展开代码
其中，swaggerOptions 是 hapi-swagger 插件的配置项，我们指定了 API 文档的标题和版本号。
插件注册完毕后，我们需要对每个 API route 进行配置，具体地，在 options 属性中指定以下内容：
tags- 标记 API 所属的标签，便于分类和过滤description- 描述 API 的功能notes- 提供 API 的更详细的信息plugins- 配置 API 的响应信息，包括状态码和 schema 定义
需要注意的是，为了获取 Joi 对象，我们需要先导入 joi 模块：
const Joi = require('@hapi/joi');
- 访问 Swagger 文档
启动 Hapi 后，我们可以通过 http://localhost:3000/documentation 访问 Swagger 文档：
在右上角的搜索框中，输入 /hello，即可找到我们刚刚编写的 API：
在该页面，我们可以查看 API 的详细信息，包括请求和响应的 schema 定义、参数列表和返回值示例等。
总结
本文介绍了如何在 Hapi 框架中集成 Swagger 文档。通过集成 Swagger，我们可以方便地生成和查看 API 文档，使 API 的使用和调试变得更加简单。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/648ae4e948841e9894930c42
