什么是 Fastify？
Fastify 是一个快速、低开销且基于 Node.js 的 web 框架。它提供了一系列内置的插件，例如自行推断的请求有效负载验证、请求和响应性能监控、高效的错误处理功能、跨站点请求伪造保护和日志记录等功能。因此，Fastify 对于构建高性能、安全和可扩展的 web 应用程序来说是一种非常好的选择。
什么是 Swagger UI？
Swagger UI 是 Swagger 生态系统中最常用的开源工具之一，它提供了一个交互式的 API 文档页面，可以帮助团队更好地理解和使用 API。在 Swagger UI 中，用户可以浏览所有可用操作、参数类型和可接受的请求负载，而无需自行调用 API。
将 Swagger UI 集成到 Fastify 应用程序中
下面将演示如何在 Fastify 应用程序中配置 Swagger UI 来提供 API 文档。假设我们已经有一个简单的 Fastify 应用程序，其中定义了一个根路由 /。接下来，我们需要安装 fastify-swagger 插件，并将其添加到 Fastify 应用程序中。
npm install fastify-swagger
-- -------------------- ---- ------- ----- ------- - -------------------- ------- ---- -- -------------------------------------------- - ------------ ----- ------------ -------- -------- - ----- - ------ -------- -------- - - -- ---------------- ----- --------- ------ -- - ------ - ------ ------- - -- -------------------- ------- -------- -- - -- ------- - ------------------------- ----------------- - --展开代码
在上述示例中，我们导入了 fastify-swagger，并在 Fastify 应用程序中注册它。我们设置了 exposeRoute 选项来启用 /docs/swagger 路径，该路径将显示所有可用的 API 路由。与此同时，我们还设置了 routePrefix 选项以指定 Swagger UI 使用的 URL 。
当我们向应用程序发出 GET 请求时，将返回以下响应。
{ "hello": "world" }
如果您现在打开 http://localhost:3000/docs/swagger，则应该可以看到 Swagger UI 界面。
添加 Swagger 路由和操作
Fastify-swagger 扫描 Fastify 应用程序以查找所有定义的路由并生成相应的 Swagger 文档。最简单的方法是使用 Fastify 路由方法绑定路由操作，然后在操作中定义参数以及请求和响应模式。
-- -------------------- ---- ------- ------------------- - ------- - ------- - --- - ----- -------- - -- --------- - ---- - ----- --------- ----------- - --- - ----- -------- -- ----- - ----- -------- - - - - - -- ----- --------- ------ -- - ----- - -- - - -------------- ------ - --- ----- ----- ------ - --展开代码
以上示例中，我们定义了一个包含名为 id 参数的 GET 路由，该参数的类型为 string。我们还定义了带有 200 状态代码的响应模式，该响应模式包含 id 和 name 属性。注意，这里的操作是异步的。
现在，Swagger UI 应当为您的 Fastify 应用程序生成一个新的路由和操作。
高级设置
Fastify-swagger 支持许多高级设置，其中包括路由映射、全局标记、安全定义、集成测试工具等。您可以通过在 fastify.register 方法中添加额外的选项来为 Swagger UI 配置这些设置。
-- -------------------- ---- ------- -------------------------------------------- - ------------ -------- -------- - ----- - ------ -------- -------- -- ----- ------------ -------- --------- --------- --------------------- --------- --------------------- -------------------- - ------- - ----- --------- ----- --------- --- -------- - - -- ------------ ----- ------------- ----- ---------------------------- ----- ------------------ --------------- ----- --------- -------------- - ----- ---------------- -- --------- - ------------- ------- ------------ ----- -- --------- -- ------- -- -- --展开代码
在上面的示例中，我们设置了 schemes 参数以指示应用程序使用的协议。此外，我们还添加了 consumes 和 produces 参数，以指示应用程序支持的媒体类型。我们还添加了 securityDefinitions 参数，以定义应用程序使用的安全验证规范。最后，我们添加了一些 Swagger UI 配置选项，例如文档扩展配置和静态资源路径。
结语
在这篇文章中，我们学习了如何将 Swagger UI 集成到 Fastify 应用程序中，以便为开发人员提供直观、友好的 API 文档。我们还展示了如何定义路由和操作，以及如何使用高级设置来自定义 Swagger UI 特定的行为和属性。
Fastify-swagger 插件可以使 API 服务的开发变得更加高效和友好。通过使用 Swagger UI，团队可以共享和理解 API 标准，减少沟通成本并提高代码质量。希望这篇文章能够帮助您开始使用 Fastify-swagger，并为您的 API 服务开发提供令人愉悦的体验。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/67c0ff2c314edc2684841fa7
