在开发前端应用时，API 文档的编写是必不可少的一部分。而手动维护 API 文档是一项繁琐且容易出错的任务。Swagger 是一种 API 规范，通过描述 API 的 JSON 或 YAML 文件来规范 API 的输出和输入格式。在本文中，我们将探讨如何在 Express.js 应用程序中集成 Swagger 自动化生成 API 文档，并提供示例代码。
安装 Swagger
首先，我们需要使用 Node.js 包管理器（npm）安装 Swagger。在终端中运行以下命令：
npm install -g swagger
安装完成后，我们可以运行以下命令创建一个新的 Swagger 项目：
swagger project create <project-name>
这将创建一个包含示例代码和配置文件的 Express.js 应用程序。
编写 Swagger 配置文件
Swagger 配置文件是一个 JSON/YAML 文件，描述了 API 的输入和输出格式，以及一些其他细节。以下是一个示例配置文件：
-- -------------------- ---- -------
-------- -----
-----
------ -- ---
-------- -----
--------- ---
--------
- ----
----- --------------
------
-------
----
-------- ---- --- -----
----------
----
------------ --
---------
- ----------------
------------
----
-------- --- - ---- -- --
-----------
- ----- --
--- ----
--------- ----
----- ------
----------
----
------------ --
---------
- ----------------在此示例中，我们定义了一个名为“My API”的 API，使用的版本为“1.0.0”，基本路径为“/v1”，支持 HTTP 协议，并在本地主机上运行。我们还定义了两个路由：/users 和 /users/{id}，它们分别列出所有用户和按 ID 获取用户。每个路由都定义了一个“get”方法，指定了一些参数和输出格式。
集成 Swagger 到 Express.js 应用程序中
要将 Swagger 集成到 Express.js 应用程序中，我们需要执行以下步骤：
将 Swagger 配置文件保存到项目根目录中的“api”文件夹中，并重命名为“swagger.yaml”。
在 app.js 文件中导入 Swagger 并将其应用于应用程序：
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./api/swagger.yaml');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));在此示例中，我们导入了 Express.js、Swagger UI 和我们刚刚创建的 Swagger 配置文件。我们还将 Swagger UI 安装在“/api-docs”路径下，并将其与我们的 Swagger 配置文件一起设置。
- 在路由文件中编写路由：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ------ - ----------------- -------------------- -------- ----- ---- ----- - -- ------ - ---- -- ----- --- ------------------------ -------- ----- ---- ----- - -- ------ - ------ ---- -- -- --- -------------- - -------
在此示例中，我们定义了两个路由，它们与我们在 Swagger 配置文件中定义的路由一样。但是，我们并没有在这里指定输出格式或输入参数。
- 在路由文件中使用 Swagger 修饰器（Swagger Decorator）：
-- -------------------- ---- -------
----- ------- - -------------------
----- ------------ - -------------------------
----- ------ - -----------------
----- ------- - -
----------- -
-------- --------
----- -
------ --- -----
-------- --------
--
--
----- ------------------
--
----- ----------- - ----------------------
---
- --------
- -------
- ----
- -------- ---- --- -----
- ---------
- - ----------------
- ----------
- ----
- ------------ --
- ----
- ------------ --- -------
--
-------------------- -------- ----- ---- ----- -
-- ------ - ---- -- -----
---
---
- --------
- ------------
- ----
- -------- --- - ---- -- --
- -----------
- - ----- --
- --- ----
- --------- ----
- ----- ------
- ---------
- - ----------------
- ----------
- ----
- ------------ --
- ----
- ------------ --- -------
- ----
- ------------ --- -----
--
------------------------ -------- ----- ---- ----- -
-- ------ - ------ ---- -- --
---
-------------- - -------在此示例中，我们使用 swagger-jsdoc 生成 Swagger 注释。这样，我们可以在路由中指定输出格式和输入参数，同时保持 Swagger 配置文件的清晰和易于维护。我们使用 @swagger 标记修饰注释，以指定每个路由的参数、响应及其它细节。
运行程序并查看自动生成的 API 文档
现在我们已经在应用程序中编写了 API 路由，并使用 Swagger 修饰器定义了输入和输出格式。在终端中运行以下命令启动应用程序：
npm start
现在，我们可以在浏览器中打开“http://localhost:3000/api-docs”，就可以看到自动生成的 API 文档了。
结论
通过将 Swagger 集成到 Express.js 应用程序中，我们可以自动化生成 API 文档，减轻了手动维护 API 文档的负担。在本文中，我们演示了如何在应用程序中使用 Swagger UI，并在路由中使用 Swagger 修饰器定义输入和输出格式。我们也展示了如何结合 Swagger 配置文件来大幅减小代码的重复性。希望本文能帮助您了解 Swagger 并开始编写自动化 API 文档！
参考资料
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/677667716d66e0f9aa20b625