Fastify 是一个高效、低开销的 Node.js web 框架，它支持异步请求处理和路由，同时还提供了易于扩展的插件架构。在开发 RESTful API 时，我们通常需要编写文档来描述 API 的使用方法和参数，这样才能让其他开发者快速上手并使用我们的 API。然而，手动编写文档费时费力，而且容易出错。本文将介绍如何使用 Fastify-swagger 插件来自动生成 API 文档。
安装 Fastify 和 Fastify-swagger
首先，你需要安装 Fastify 和 Fastify-swagger。
npm install fastify fastify-swagger --save
配置 Fastify-swagger
Fastify-swagger 插件会根据路由信息自动生成文档，因此我们需要在路由中添加一些元数据，以便插件能够正确地识别路由参数和响应格式。我们可以通过装饰器语法来添加元数据，如下所示：
-- -------------------- ---- -------
----- ------- - --------------------
----- ------- - --------------------------
------------------------- -
------------ -----------------
-------- -
----- -
------ --- -----
------------ ---- ---------------
-------- -------
--
------------- -
---- ---------------------
------------ ----- ---- ---- -----
--
--------- ---------------------
--------- --------------------
--
------------ ----
--
--------------------------- -
------- -
------- -
----- ---------
----------- -
----- -
----- ---------
------------ ----- -----
-
-
--
--------- -
---- -
----- ---------
----------- -
-------- -
----- ---------
------------ --------- --------
-
-
-
-
-
-- ----- ----- ---- -- -
------ - -------- ------ ------------------- -
--
-------------------- -- -- -
------------------- --------- -- -----------------------
--在上面的示例中，我们首先注册了 Fastify-swagger 插件，并且指定了文档的基本信息（标题、描述和版本号）、外部文档链接、请求和响应格式。接着，我们定义了一个 GET 路由，它接受一个名为 name 的参数，并返回一个包含 message 属性的对象。在路由定义中，我们使用了 schema 属性来添加元数据，它包含了请求参数和响应格式的定义。注意，请求参数的定义是一个对象，它包含了一个名为 params 的属性，它的类型是 object，它的 properties 属性包含了一个名为 name 的属性，它的类型是 string，它的描述是 User name。响应格式的定义是一个对象，它包含了一个名为 200 的属性，它的类型是 object，它的 properties 属性包含了一个名为 message 的属性，它的类型是 string，它的描述是 Greeting message。
查看文档
启动 Fastify 服务器后，你可以在浏览器中访问 http://localhost:3000/documentation 来查看文档。你会看到一个自动生成的 API 文档，其中包含了你定义的路由信息和元数据，如下所示：
总结
Fastify-swagger 插件为我们提供了一种简单而高效的方式来自动生成 API 文档。通过添加元数据到路由定义中，我们可以让插件自动识别请求参数和响应格式，并生成易于阅读的文档。如果你正在开发 RESTful API，那么 Fastify-swagger 插件将是一个不错的选择。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6510ca3f95b1f8cacd9324af