Fastify 是一款轻量级的 Node.js Web 框架，它的速度快、性能优秀、支持异步 I/O 等众多优点，使得它成为热门的 Node.js 开发框架之一。而在 Fastify 的众多工具中，fastify-swagger 插件则为我们提供了一种方便快捷的方式来生成 API 文档。如果您想要了解 Fastify 及其插件的使用，本文将为您提供详细的指导和示例。
安装 fastify-swagger
要使用 fastify-swagger 插件，我们首先需要在项目中安装它。我们可以通过以下命令在终端中安装它：
npm i fastify-swagger
接下来，我们需要在代码中引入它，然后使用 fastify.register() 注册插件：
const fastifySwagger = require('fastify-swagger')
fastify.register(fastifySwagger, {
// options
})配置插件
安装插件后，我们需要对其进行配置。最基本的配置是指定 routePrefix。我们可以通过其中一个选项指定要将接口文档托管到的路径：
fastify.register(fastifySwagger, {
routePrefix: '/documentation'
})这将生成一个路径为 /documentation/swagger 的文档页面，在这里您可以看到所有指定的 API 的详细信息。
添加路由
接下来，我们需要添加要在接口文档中显示的路由，这些路由应该遵循 OpenAPI 规范。我们可以通过 addSchema() 方法在 Fastify 实例中添加路径。
-- -------------------- ---- -------
------------------------- -
------- -
------- -
----- ---------
----------- -
--- -
----- ----------
------------ ---- ---
-
-
--
--------- -
---- -
----- ---------
----------- -
--- -
----- ----------
------------ ---- ---- ----
--
----- -
----- ---------
------------ ---- ---- ------
-
-
-
-
-
-- ----- ------ -- -
-- ----- -----
--这将创建一个名称为 /books/:id 的路径，该路径使用一个包含 params 和 response 对象的 JSON 架构对象来规定请求的参数和响应的格式。接下来，我们需要将该路径添加到 Fastify 实例中：
-- -------------------- ---- -------
------------------------- -
------- -
-- ---
-
-- ----- ------ -- -
-- ---
--------------
---- -------------
----- ---------
----------- -
--- -
----- ----------
------------ ---- ---- ----
--
----- -
----- ---------
------------ ---- ---- ------
-
-
--这将使用 $id 属性创建和命名一个新的 JSON 架构对象，并将其添加到 Fastify 实例中。
启动 Fastify
现在我们已经添加了所有路由，我们只需要启动 Fastify，访问 /documentation/swagger 路径，就可以在浏览器中查看我们生成的接口文档了。
fastify.listen(3000, (err) => {
if (err) {
console.log(err)
process.exit(1)
}
console.log(`Server is running on port: ${fastify.server.address().port}`)
})使用示例
以下代码是一个完整的示例，展示了如何使用 Fastify 和 fastify-swagger 插件来生成 API 文档。
-- -------------------- ---- -------
----- ------- - --------------------
----- -------------- - --------------------------
-------------------------------- -
------------ -----------------
-------- -
----- -
------ -------- ---------
------------ -------- ------- ---------
-------- -------
--
--------- ---------------------
--------- --------------------
--
------------ ----
--
------------------------- -
------- -
------- -
----- ---------
----------- -
--- -
----- ----------
------------ ---- ---
-
-
--
--------- -
---- -
----- ---------
----------- -
--- -
----- ----------
------------ ---- ---
--
----- -
----- ---------
------------ ------
-
-
-
-
-
-- ----- ------ -- -
------------
--- --------------
----- ----- -----
--
--------------
---- -------------
----- ---------
----------- -
--- -
----- ----------
------------ ---- ---
--
----- -
----- ---------
------------ ------
-
-
--
-------------------- ----- -- -
-- ----- -
----------------
---------------
-
------------------- -- ------- -- ----- ----------------------------------
--启动该应用，然后在浏览器中访问 http://localhost:3000/documentation/swagger，即可看到 Fastify 生成的 API 文档。
总结
在本文中，我们学习了使用 Fastify 和 fastify-swagger 插件进行 API 文档生成的方法。通过注册插件、添加路由、并将其添加到 Fastify 实例中，我们可以方便地生成符合 OpenAPI 规范的 API 文档。通过这种方式，我们可以更容易地理解 API 的工作方式，加快应用程序的开发速度，并提高代码质量。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64924f5748841e989401bb8f