Fastify 是一款高效、低开销的 Node.js Web 框架。 它具有优秀的性能和安全、可维护性高的 API 开发体验。而 Swagger 是一个非常优秀的 API 文档生成工具，可以通过静态分析程序源代码或者配置文件生成API文档。本文将讨论如何在 Fastify 中使用 Swagger 生成 API 文档，以便更好的展示接口使用信息和帮助前端开发人员理解和使用 API。
环境
- Node.js 版本：12.x 及以上
- Fastify 版本：2.5.0 及以上
- Swagger 版本：3.25.0 及以上
安装步骤
1. 安装 fastify-swagger
在 Fastify 应用程序中使用 fastify-swagger 插件以自动生成 API 文档。 运行以下命令以安装 fastify-swagger 插件：
npm i fastify-swagger --save
2. 配置 Swagger
可以使用 Yml 或 JSON 格式为您的 Fastify 应用程序编写 Swagger 规范，仅需在应用程序配置对象中，将 swagger 选项设置为需要的配置即可。
下面是一个简单的 Swagger 配置示例：
-- -------------------- ---- -------
-
------- -----------------
----------- ----
---------- -
-------
-------
--
----------- -
------------------
--
----------- -
------------------
--
-------------- --
-3. 注册 fastify-swagger 插件
直接在 Fastify 应用程序注册 fastify-swagger 插件，如下：
-- -------------------- ---- -------
----- ------- - --------------------
----- -------------- - --------------------------
-------------------------------- -
-------- -
----- -
------ ---- ----
------------ ---- ------
-------- -------
--
------------ ---
----- ----------------- -- ----------
--------- ---- -- ------
-------- --------- -- ----
--------- --------------------- -- -----------------
--------- -------------------- -- -----------------
--
------------ ---- -- ---- ---------- --------------------------
--如何使用 fastify-swagger 插件
在上面的注册 fastify-swagger 中看到 exposeRoute: true 的配置，那么打开如下地址 http://localhost:3000/docs，就能看到 Swagger 文档了。
注意，我们想要显示此端点，需要把 exposeRoute 设为 true。
现在，您已经准备好了文档和应用程序 - 现在开始定义您的 API 。
Swagger 路径操作装饰器
Swagger 规范支持描述的 HTTP 路径操作，例如 POST http://localhost:3000/v1/users 。Swagger标准中为你提供了一个用于描述这些操作的装饰器，每个装饰器作用于一个操作：@POST()、@GET()、@PUT()、@DELETE()、@OPTIONS()、@HEAD()、@PATCH() 和 @ALL()。
例如：
fastify.post('/api/v1/users', async (req, res) => {});Fastify Swagger 提供了 @Request() 和 @Response() 装饰器，它们用于批注输入请求和输出响应，并且是 Swagger API 自描述行成员的必要部分。
下面是一个简单的 Router 示例：
-- -------------------- ---- -------
----------------------------- -
------- -
----- -
----- ---------
----------- -
----- - ----- -------- --
---- - ----- -------- -
-
--
--------- -
---- -
----- ---------
----------- -
-------- - ----- -------- -
-
-
-
-
-- ----- ----- ---- -- -
------ - -------- ----- ------- -------------- -
--注意，我们在 fastify.post 路由注册方法输出的第二个参数中添加了 schema。这样，fastify-swagger 就能拿到路由的请求参数和响应参数。
总结
现在，我们将 Fastify 和 Swagger 工具结合在一起生成 API 文档。Fastify 是一个优秀的开源项目，为前端开发提供了高效、简洁的 API 实现。而 Swagger 在定义、描述、生成 API 文档等方面再实用不过了。我们相信，将这两种工具结合使用既可以提高开发的效率，同时也能够更好地规范 API 文档。我们希望通过本文内容，能够让读者更好的理解和使用 Fastify 和 Swagger。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6495806148841e98942a863e