Swagger 是一个开源的项目，旨在描述 RESTful API 以及提供可视化的接口文档。对于前端开发人员而言，Swagger 文档可以帮助他们理解后端提供的接口并快速上手。
Fastify 是一个快速、易扩展的 Web 框架，它已经内置了对 Swagger 的支持。本篇文章将介绍如何在 Fastify 中使用 Swagger 文档。
安装 Swagger 插件
使用 npm 安装 fastify-swagger 插件：
--- ------- ------ ---------------
然后在 Fastify 应用程序中注册插件：
----- ------- - ---------------------
----- ------- - ---------------------------
------------------------- -
------------ -----------------
-------- -
----- -
------ -------- ---------
------------ -------- ------------- --- ---------
-------- -------
--
------------- -
---- ---------------------
------------ ----- ---- ---- -----
--
----- -----------------
-------- ---------
--------- ---------------------
--------- --------------------
--
------------ ----
---
-------------------- -------- ----- -------- -
-- ----- -
-------------------
----------------
-
------------------- --------- -- -------------
---routePrefix：文档路由前缀。swagger：设置 Swagger 的元数据信息。exposeRoute：如果为true，则会向 Fastify 应用程序添加documentation路由。
编写 Swagger 文档
Fastify 提供了一种简单的方式来编写 Swagger 文档。
可以将 Swagger 文档定义直接写到路由定义函数的配置中，如下所示：
---------------
------- -------
---- ----
------- -
----- -
----- ---------
--------- -------- -------
----------- -
----- - ----- -------- --
---- - ----- -------- -
-
--
--------- -
---- -
----- ---------
--------- -------
----------- -
--- - ----- -------- -
-
-
--
----- --------
--
-------- -------- ----- ------ -
----- -- - -----------------------------------
------------ -- ---
-
---在上述例子中，我们可以看到 schema 对象中的几个选项。这些选项设置了请求体和响应的期望值。我们还可以为路由添加标签。
在调用路由时，Swagger 编辑器将显示所使用的元数据以及其在 Swagger 文档中的位置。
Swagger 维护
如果要在整个 Fastify 应用程序中使用 Swagger，那么将 Swagger 定义编写到路由中显然是不可行的。在这种情况下，可以考虑将 Swagger 定义写入单独的文件并将其导入应用程序。
让我们来看一个示例，假设我们有一个 users.js 文件，其中定义了有关用户的路由：
----- ------ - -
----- -
----- ---------
--------- -------- -------
----------- -
----- - ----- -------- --
---- - ----- -------- -
-
--
--------- -
---- -
----- ---------
--------- -------
----------- -
--- - ----- -------- -
-
-
--
----- --------
--
----- -------- ------------------- -------- -
----------------- - ------ -- ----- -------- ----- ------ -
----- -- - -----------------------------------
------------ -- ---
---
-
-------------- - -----------我们可以将 Swagger 定义写入单独的文件：
-
------- -
- ------- ------- -------------- ----- ------ -
--
-------- -
-------- -
------- -
------- - ------ --
---------- ------- - --- ------
-------------- ------- - --- ------
----------- - ------------------ --
----------- - ------------------ --
------------- -
-
----- -------
------- -------
----------- -----
--------- -
------- --------------------------
-
-
--
------------ -
------ -
-------------- ----- ---------
--------- -
------- ----------------------
-
-
-
-
-
--
-------------- -
------------- -
------- ---------
----------- - ------- ----- --
------------- -
------- - ------- -------- --
------ - ------- -------- -
-
--
--------- -
------- ---------
----------- - ---- --
------------- -
----- - ------- -------- -
-
-
-
-然后在启动应用程序时导入这个文件：
----- ------- - ---------------------
----- ------- - ---------------------------
----- ---------- - -------------------
----- ----------------- - --------------------------
------------------------- -
------------ -----------------
-------- ------------------
------------ ----
---
-----------------------------
-------------------- -------- ----- -------- -
-- ----- -
-------------------
----------------
-
------------------- --------- -- -------------
---在上述示例中，我们使用 require('./swagger.json') 导入 Swagger 定义，并使用 register 方法注册路由和 Swagger 插件。
结论
Fastify 对 Swagger 的支持使得为 RESTful API 编写文档变得非常容易。在本文中，我们介绍了如何安装并使用 Fastify-Swagger 插件，并展示了如何编写 Swagger 文档。
当然，本文中只是给出了基础的使用示例，实际操作中，我们还可以应用更加丰富多样的选项和配置，以达到更加精细的 Swagger 文档编辑和使用效果。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/671da9689babaf620fb777a1