在现代 web 应用程序中，RESTful API 是建立客户端和服务器之间通信的重要方式，因此文档化 API 是非常重要的一步。Swagger 是一个流行的规范，它定义了一种描述 RESTful API 的方式，并提供自动生成 API 文档的工具。在本文中，我们将讨论如何将 Swagger 集成到 Hapi.js 中，实现自动生成 RESTful API 文档的目的。
Swagger 的基本概念
Swagger 是一种描述 RESTful API 的规范，它允许您使用一组结构化文件描述 API 的各个方面。主要有以下几个文件：
- Swagger UI：这是一个 HTML5 接口，允许您轻松地查看和测试您的 API。它可以让您以可视化的方式了解您的 API 的结构和呈现方式。
- Swagger 文档：这是一个 JSON 或 YAML 格式的文件，描述了您的 API 的元数据，包括资源、操作、参数、响应、安全性等等。
- Swagger Codegen：这是一个可执行的命令行工具，允许您从 Swagger 规范中自动生成客户端和服务器端代码。
在 Hapi.js 中使用 Swagger
Hapi.js 是一个流行的 Node.js web 框架，它提供了一种可扩展的插件体系结构，允许我们方便地使用 Swagger 来生成 API 文档。
首先，我们需要安装 Swagger 相关的 NPM 包和插件：
npm install swagger-ui hapi-swagger inert vision
swagger-ui：Swagger UI 是一个功能强大的界面，用于显示我们在 Swagger 规范中定义的 API 文档。hapi-swagger：这是一个 Hapi 插件，允许我们根据 Swagger 规范自动生成 API 文档。inert和vision：这是 Hapi 插件，允许我们向 Hapi 服务器中添加静态文件和模板文件服务。
接下来，我们可以定义 Swagger 规范，以描述我们的 API。下面是一个简单的例子：
-- -------------------- ---- -------
----- ---- - ----------------------
----- --- - ---------------
----- ----- - -----------------
----- ------ - ------------------
----- ----------- - ------------------------
----- ---- - ----- -- -- -
----- ------ - -------------
----- -----
----- ------------
------- -
----- ----
-
---
----- -------------- - -
----- -
------ ------- --- ---------------
-------- ------
------------ -- ------ --- ------------- ----- ------- --- --------
--
--------- -------
-------------- ---------
--
----- -----------------
------
-------
-
------- ------------
-------- --------------
-
---
--------------
------- ------
----- -------------
-------- -
----- --------
------------ ---- --------
------ -------- - ----- ----------
--------- ---
-------- --------- -- -- -
------ ------ --------
-
-
---
----- ---------------
------------------- ------- -- ---- -----------------
--
-------在这个简单的例子中，我们定义了一个 /api/hello 的路由，并将它标记为 Swagger 文档中的 API。我们使用 hapi-swagger 插件，将 swaggerOptions 对象包含在 server 注册选项中。这个对象定义了我们的 API 文档的元数据，例如标题、描述、版本、basePath 等等。我们还使用 validate 属性来定义请求参数的有效性。
在启动服务器之后，访问 http://localhost:3000/documentation 即可看到我们自动生成的 API 文档。
总结
通过将 Swagger 集成到 Hapi.js 中，我们可以轻松地为我们的 RESTful API 自动生成文档。在这篇文章中，我们讨论了 Swagger 的基本概念，并给出了一个简单的例子来说明如何将 Swagger 集成到 Hapi.js 中。希望这篇文章对您有所帮助，欢迎您尝试将 Swagger 集成到您的项目中，并实现自动生成 RESTful API 文档的目的。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64b10a9d48841e9894d55665