在前端开发中，API 文档的编写是不可避免的一个过程。然而，手动编写 API 文档是一件费时费力的工作，而且容易出错。为了解决这个问题，我们可以使用 Swagger UI 来自动生成 API 文档。在 Fastify 框架中，集成 Swagger UI 自动生成 API 文档非常简单，本文将详细讲解如何集成。
什么是 Fastify 框架？
Fastify 是一个快速、低开销、可扩展的 Node.js Web 框架。它专注于提供最佳的开发体验，而不是强制使用某些库或工具。Fastify 的核心理念是性能和安全性，以及尽可能少的开销。因此，Fastify 被广泛用于构建高性能的 Web 应用程序和服务。
什么是 Swagger UI？
Swagger UI 是一个用于可视化和交互式地浏览和测试 RESTful API 的开源工具。它可以从 Swagger 规范（OpenAPI 规范）中生成 API 文档，并提供了一个可视化的界面，让用户可以轻松地浏览和测试 API。
Fastify 中集成 Swagger UI 自动生成 API 文档的步骤
下面是在 Fastify 中集成 Swagger UI 自动生成 API 文档的步骤：
步骤一：安装相关依赖
首先，我们需要安装一些必须的依赖：
npm install fastify-swagger --save npm install fastify-oas --save
其中，fastify-swagger 是一个 Fastify 插件，用于生成 Swagger 规范（OpenAPI 规范）的 JSON 文件，而 fastify-oas 是用于生成 Swagger UI 的 Fastify 插件。
步骤二：集成 fastify-swagger 插件
在 Fastify 中，我们需要使用 fastify-swagger 插件来生成 Swagger 规范的 JSON 文件。在 Fastify 的启动文件中添加以下代码：
-- -------------------- ---- -------
----- -------------- - --------------------------
-------------------------------- -
------------ -----
------------ --------
-------- -
----- -
------ -------- -----
------------ ---- ------------- ----- ------- ----
-------- -------
--
------------- -
---- ---------------------
------------ ----- ---- ---- -----
--
--------- ---------------------
--------- --------------------
-
--在上面的代码中，我们使用 fastify-swagger 插件来注册 Swagger UI。exposeRoute 选项用于在 /docs 路径上公开 Swagger UI。routePrefix 选项用于指定 Swagger UI 的路由前缀。swagger 选项用于定义 Swagger 规范的元数据，如标题、描述、版本、消耗和生产内容类型等。
步骤三：集成 fastify-oas 插件
接下来，我们需要使用 fastify-oas 插件来生成 Swagger UI。在 Fastify 的启动文件中添加以下代码：
-- -------------------- ---- -------
----- ---------- - ----------------------
---------------------------- -
------------ --------
-------- -
----- -
------ -------- -----
------------ ---- ------------- ----- ------- ----
-------- -------
--
------------- -
---- ---------------------
------------ ----- ---- ---- -----
--
--------- ---------------------
--------- --------------------
--
------------ ----
--在上面的代码中，我们使用 fastify-oas 插件来注册 Swagger UI。routePrefix 选项用于指定 Swagger UI 的路由前缀。swagger 选项用于定义 Swagger 规范的元数据，如标题、描述、版本、消耗和生产内容类型等。exposeRoute 选项用于在 /docs 路径上公开 Swagger UI。
步骤四：编写 API
现在，我们已经成功集成了 Swagger UI 自动生成 API 文档所需的插件。接下来，我们需要编写一些 API，以便 Swagger UI 可以生成相应的 API 文档。以下是一个示例 API：
-- -------------------- ---- -------
--------------------- -
------- -
--------- -
---- -
----- ---------
----------- -
-------- - ----- -------- -
-
-
-
-
-- ----- --------- ------ -- -
------ - -------- ------ ------- -
--在上面的代码中，我们使用 Fastify 的 get 方法定义了一个 /hello 路径的 API，它返回一个包含 message 属性的 JSON 对象。我们还使用了 schema 选项来定义 API 的响应模式。
步骤五：查看生成的 API 文档
现在，我们已经成功地集成了 Swagger UI 自动生成 API 文档所需的插件，并编写了一些 API。我们可以通过访问 /docs 路径来查看生成的 API 文档。在浏览器中打开 http://localhost:3000/docs，即可查看生成的 API 文档。
总结
在本文中，我们讲解了如何在 Fastify 框架中集成 Swagger UI 自动生成 API 文档。我们先介绍了 Fastify 和 Swagger UI 的概念，然后详细讲解了如何集成 fastify-swagger 和 fastify-oas 插件。最后，我们在一个示例 API 中演示了如何使用 Swagger 规范来定义 API 的响应模式。希望本文对您有所帮助，谢谢阅读！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/651405e295b1f8cacdc7f632