前言
在开发 Web 应用程序时，API 文档是非常重要的。它们为开发者提供了对 API 的详细描述，包括如何使用它，如何调用它，以及返回的数据格式等。在开发过程中，我们需要不断更新和维护 API 文档，以确保它们与代码的实际实现相符。
Fastify 和 Swagger 是两个非常流行的工具，它们可以帮助我们自动生成 API 文档。Fastify 是一个快速、低开销、易于使用的 Web 框架，而 Swagger 是一个开源的 API 文档工具，它可以自动生成 API 文档，并提供一个交互式的 UI 以便于测试 API。
在本文中，我们将学习如何使用 Fastify 和 Swagger 进行 API 文档生成，并提供一些示例代码以帮助您更好地理解这些工具。
安装 Fastify 和 Swagger
在开始之前，我们需要先安装 Fastify 和 Swagger。您可以使用以下命令在您的项目中安装它们：
npm install fastify swagger-ui-fastify --save
创建 Fastify 应用程序
接下来，我们将创建一个 Fastify 应用程序，并在其中定义一些路由和 API。以下是一个简单的示例：
-- -------------------- ---- -------
----- ------- - -------------------- ------- ---- --
---------------- ----- --------- ------ -- -
------ - ------ ------- -
--
------------------------- ----- --------- ------ -- -
----- - -- - - --------------
------ - --- ----- ----- ---- -
--
-------------------- ----- -------- -- -
-- ----- -
----------------------
---------------
-
------------------------ --------- -- ------------
--在上面的代码中，我们创建了一个 Fastify 应用程序，并在其中定义了两个路由。第一个路由处理根路径 /，并返回一个简单的 JSON 对象。第二个路由处理 /users/:id，并返回一个包含用户 ID 和名称的 JSON 对象。
添加 Swagger 支持
现在，我们已经创建了一个 Fastify 应用程序，并定义了一些路由和 API。接下来，我们将添加 Swagger 支持，以便我们可以自动生成 API 文档。
要添加 Swagger 支持，我们需要使用 swagger-ui-fastify 插件。以下是一个示例：
-- -------------------- ---- -------
----- ------- - -------------------- ------- ---- --
----- ------- - --------------------------
----- ------------- - --------------------------------
------------------------- -
------------ -----------------
-------- --------------
------------ ----
--
---------------- ----- --------- ------ -- -
------ - ------ ------- -
--
------------------------- -
------- -
------- -
----- ---------
----------- -
--- - ----- -------- -
--
--------- ------
-
-
-- ----- --------- ------ -- -
----- - -- - - --------------
------ - --- ----- ----- ---- -
--
-------------------- ----- -------- -- -
-- ----- -
----------------------
---------------
-
------------------------ --------- -- ------------
--在上面的代码中，我们首先使用 fastify-swagger 插件注册了 Swagger。我们还定义了一个名为 swagger-config.json 的配置文件，它包含了一些 Swagger 的配置选项。接下来，我们使用 exposeRoute 选项将 Swagger UI 暴露为一个路由。这意味着我们可以在浏览器中访问 /documentation，并查看自动生成的 API 文档。
我们还对 /users/:id 路由进行了一些更改。我们添加了一个名为 schema 的选项，它描述了路由的参数和返回值。这些信息将用于自动生成 API 文档。
编写 Swagger 配置文件
现在，我们已经添加了 Swagger 支持，并定义了一些路由和 API。接下来，我们将编写一个 Swagger 配置文件，以便自动生成 API 文档。
以下是一个示例 Swagger 配置文件：
-- -------------------- ---- -------
-
---------- --------
------- -
-------- -------- -----
-------------- -- ------ ------- -----
---------- -------
--
---------- -
-
------ ------------------------
-------------- ------ -------
-
--
-------- -
---- -
------ -
---------- ---- - ----- ----- ---------
------------ -
------ -
-------------- ----------- ----------
---------- -
------------------- -
--------- -
------- ---------
------------- -
-------- -
------- --------
-
-
-
-
-
-
-
-
--
-------------- -
------ -
---------- ---- - ---- -- ----
------------- -
-
------- -----
----- -------
-------------- ----- ----
----------- -----
--------- -
------- --------
-
-
--
------------ -
------ -
-------------- ----------- ----------
---------- -
------------------- -
--------- -
------- ---------
------------- -
----- -
------- --------
--
------- -
------- --------
-
-
-
-
-
-
-
-
-
-
-在上面的代码中，我们定义了一个包含一些路由和 API 的 Swagger 配置文件。该文件使用 OpenAPI 3.0 规范，并包含以下内容：
info：包含有关 API 的基本信息，例如标题、描述和版本。servers：包含 API 的所有可用服务器的列表。paths：包含所有 API 路径的列表，以及每个路径的操作（例如 GET、POST、PUT 等）。
在每个路径操作中，我们定义了一些信息，例如概要、参数和响应。这些信息将用于自动生成 API 文档。
查看自动生成的 API 文档
现在，我们已经创建了一个 Fastify 应用程序，并使用 Swagger 自动化工具生成了 API 文档。接下来，我们可以在浏览器中访问 /documentation，并查看自动生成的 API 文档。
在浏览器中打开 http://localhost:3000/documentation，您将看到一个交互式的 Swagger UI。该界面显示了我们在 Swagger 配置文件中定义的所有路由和 API，以及它们的参数和响应。您可以使用 Swagger UI 来测试 API，并查看生成的文档。
结论
在本文中，我们学习了如何使用 Fastify 和 Swagger 进行 API 文档生成。我们创建了一个 Fastify 应用程序，并在其中定义了一些路由和 API。接下来，我们添加了 Swagger 支持，并编写了一个 Swagger 配置文件，用于自动生成 API 文档。最后，我们在浏览器中查看了自动生成的 API 文档，并测试了 API。
使用 Fastify 和 Swagger 进行 API 文档生成是一个非常简单和有效的方法。它可以帮助我们更好地维护和更新 API 文档，并为开发者提供一个方便的测试界面。如果您正在开发 Web 应用程序，并希望为您的 API 自动生成文档，那么 Fastify 和 Swagger 绝对是值得一试的工具。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6742ab6edb344dd98de12df7