Fastify 是一个快速、低开销的 Web 框架，它具有强大的插件架构。Swagger 是一种非常流行的 API 设计、测试和文档工具，它可以让我们更加方便地组织和维护 API 文档。在本文中，我们将学习如何在 Fastify 框架中使用 Swagger 生成 API 文档。
安装
为了使用 Swagger，我们需要安装以下两个模块：
npm install fastify-swagger --save npm install swagger-ui-fastify --save
其中，fastify-swagger 是一个 Fastify 插件，用于自动生成 JSON 格式的 Swagger 文档。swagger-ui-fastify 是一个 Fastify 插件，它提供了一个方便的 UI，可以让我们在浏览器中查看 API 文档。
配置
使用 Swagger 生成 API 文档的第一步是配置 fastify-swagger 插件。配置需要指定 API 文档的元数据，例如 API 的标题、描述、版本号等。以下是一个示例：
-- -------------------- ---- -------
----- ------- - --------------------
------- ----
---
----- ------- - -
-------- -
----- -
------ --- -----
------------ -- ------ ------- -----
-------- -------
--
--
------------ ----
--
-------------------------------------------- ---------在这个示例中，我们注册了 fastify-swagger 插件，并指定了 API 文档的元数据。我们还设置了 exposeRoute: true，这样我们就可以访问 /documentation 路径来查看文档了。我们需要在插件注册之前注册 fastify-swagger。
撰写 API 文档
在我们启用 fastify-swagger 插件之后，我们需要为每个路由定义 Swagger 文档。以下是一个示例：
-- -------------------- ---- -------
--------------------- -
------- -
------------ ---- ----- -------
----- ----------
--------- -
---- -
------------ ----------- ----------
----- ---------
----------- -
-------- - ----- -------- -
-
-
-
--
-------- ----- --------- ------ -- -
------ - -------- ------ ------ --
-
---在这个示例中，我们为 /hello 路由定义了 Swagger 文档。我们使用了 schema 选项来指定文档的元数据，例如路由的描述、标签和响应内容。我们还指定了路由的处理程序，它返回一个包含 message 属性的对象。这个对象定义了 /hello 路由的成功响应。
查看文档
我们在代码中配置 Swagger，现在我们需要在浏览器中查看 API 文档。我们可以使用 swagger-ui-fastify 插件提供的 UI，访问 /documentation 路径来查看 API 文档。以下是一个示例：
fastify.register(require('swagger-ui-fastify'), {
swagger: {
url: '/swagger.json'
}
});在这个示例中，我们注册了 swagger-ui-fastify 插件，并指定了要显示的文档的 URL。我们需要将 URL 设置为自动生成的 JSON 格式的 Swagger 文档的路径。此 JSON 文件由 fastify-swagger 插件生成。
现在我们可以访问 /documentation 路径，查看自动生成的 API 文档了。
总结
使用 Swagger 生成 API 文档可以让我们更加方便地组织和维护文档。在本文中，我们学习了如何在 Fastify 框架中使用 Swagger 生成 API 文档。我们安装了 fastify-swagger 和 swagger-ui-fastify 插件，然后配置了元数据和 Swagger 文档。最后，我们在浏览器中访问了 /documentation 路径，查看自动生成的 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/647b021d968c7c53b0695b40