Swagger 是一种 API 规范和工具集，用于设计、构建、文档化和测试 RESTful API。它可以帮助开发者快速创建和维护 API 文档，并提供一个交互式的 API 测试界面。在本文中，我们将介绍如何在 Express.js 中集成 Swagger，并使用它来创建和管理 API 文档。
安装 Swagger
首先，我们需要安装 Swagger。可以使用 npm 安装 Swagger UI 和 Swagger-jsdoc 两个包。
npm install swagger-ui-express swagger-jsdoc
配置 Swagger
在 Express.js 应用程序中，我们可以使用 swagger-jsdoc 来定义 API 规范，并使用 swagger-ui-express 将其呈现为交互式 API 文档。
首先，在应用程序的根目录下创建一个新文件夹，名为 docs。在 docs 文件夹下创建一个新文件，名为 swagger.json。在 swagger.json 文件中，我们可以定义 API 规范。
-- -------------------- ---- -------
-
---------- ------
------- -
---------- --------
-------- ----------- -----
-------------- ---- ------------- --- -----------
--
------- -----------------
----------- ----
---------- -
------
--
-------- -
------------- -
------ -
---------- ---- --- -------
-------------- -------- --- -------
------------ -
------ -
-------------- -- ---- -- -------
--------- -
------- --------
-------- -
------- --------------------
-
-
-
-
--
------- -
---------- ------- - --- ------
-------------- -------- - --- ------
------------- -
-
------- -------
----- -------
-------------- ----- --------
----------- -----
--------- -
------- --------------------
-
-
--
------------ -
------ -
-------------- ---- ---- ---------
--------- -
------- --------------------
-
-
-
-
-
--
-------------- -
------- -
------- ---------
------------- -
----- -
------- ---------
-------------- ----- ---
--
------- -
------- ---------
-------------- ----- -----
--
-------- -
------- ---------
-------------- ----- ------
-
-
-
-
-该文件定义了一个 API 规范，包括 API 文档的标题、描述、主机、基本路径、协议和 API 路径。我们还可以定义 API 路径的操作，例如 GET、POST、PUT 和 DELETE 等。每个操作都包括一个简要描述、详细描述、请求参数和响应模式。
接下来，在应用程序的入口文件中，我们需要引入 swagger-ui-express 和 swagger-jsdoc，并配置 Swagger 中间件。
-- -------------------- ---- -------
----- ------- - -------------------
----- --------- - ------------------------------
----- ------------ - -------------------------
----- --- - ----------
----- -------------- - -
------------------ -
----- -
-------- --------
------ ----------- -----
------------ ---- ------------- --- -----------
--
--------- ----
--
----- ------------------
--
----- ----------- - -----------------------------
-------------------- ---------------- ------------------------------在这里，我们定义了一个 swaggerOptions 对象，其中包括 API 文档的标题、描述和基本路径。我们还通过 apis 属性指定了 Swagger 规范的位置。在这个例子中，我们将规范文件放在 docs 文件夹下，并使用通配符 *.json 匹配所有 JSON 格式的文件。
然后，我们使用 swaggerJsdoc 函数来生成 Swagger 规范。最后，我们使用 swagger-ui-express 中间件将 Swagger UI 呈现为 /api-docs 路径的子路径。
使用 Swagger
现在，我们已经成功地集成了 Swagger，我们可以在浏览器中访问 http://localhost:3000/api-docs 来查看 Swagger UI。在 Swagger UI 中，我们可以看到定义的 API 路径和操作。我们可以使用 Swagger UI 来测试 API，查看请求和响应的数据。
此外，我们可以使用 Swagger UI 来生成客户端代码。在 Swagger UI 的右上角，有一个 Generate Client 按钮，点击它可以选择要生成的客户端代码的语言和框架。Swagger UI 将为我们生成一个完整的客户端代码，包括 API 调用和模型定义。
总结
在本文中，我们介绍了如何在 Express.js 中集成 Swagger，并使用它来创建和管理 API 文档。我们首先安装了 Swagger UI 和 Swagger-jsdoc 包，然后定义了一个 Swagger 规范文件。最后，我们通过配置 Swagger 中间件来呈现 Swagger UI。使用 Swagger，我们可以快速创建和维护 API 文档，并提供一个交互式的 API 测试界面。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6514f70295b1f8cacdd5b44d