随着 RESTful API 的流行，API 文档的编写变得越来越重要。Swagger 是一款可以帮助我们自动生成 API 文档的工具。在本文中，我们将学习如何在 Express.js 中集成 Swagger UI，以便更轻松地为我们的 API 提供文档支持。
步骤 1：安装 Swagger UI
为了在 Express.js 中集成 Swagger UI，我们需要安装 Swagger UI 包。可以通过以下命令来安装：
--- ------- ------------------ -------------
Swagger-jsdoc 是用于从 JSDoc 注释中自动生成 Swagger 规范的库。
Swagger UI Express 是 Swagger UI 的封装，它包含了一个 Express 中间件函数，可以轻松地将 Swagger UI 集成到我们的应用程序中。
步骤 2：配置 Swagger UI
在集成 Swagger UI 之前，我们需要为我们的 API 编写 Swagger 规范。Swagger 规范是一种描述 API 的标准化格式，它使用 YAML 或 JSON 格式。但由于 Swagger-jsdoc 允许我们从 JSDoc 注释中自动生成 Swagger 规范，让我们直接从注释开始。
--- - -------- - ----------- - -------- - ----- - --------- - - -------- - - ----- - ----------- - --------- - ----- ------ - ------ - ----- ------ - - ------- - ---- - -------- --- --- ----- - ------------ -------- - ---- -- --- ---------- ----- - ---------- - ------ - ------------ - ---------- -------- - -------- - ----------------- - ------- - ----- ----- - ------ - ----- --------------------------- --
上面的代码表示一个简单的 API 响应，其中我们的 API 将获取所有已注册的用户。
在上面代码段中，我们定义了一个 User 的模式，该模式描述了 username 和 email 属性。接着，我们定义了一个 /users 路径的 GET 请求，该请求将返回一个 User 对象数组。我们使用 JSDoc 注释来描述 API 的摘要、描述、响应等，这些信息将用于生成 Swagger 规范。
准备好 Swagger 规范后，我们可以定义 Swagger UI 中间件。
----- ------- - -------------------
----- ------------ - ------------------------
----- --------- - ------------------------------
----- --- - ----------
----- ------- - -
----------- -
-------- --------
----- -
------ ------ -----
-------- --------
------------ -- ------ --- -- --- --- ---------- -------
--
-------- -
-
---- -------------------------
--
--
--
-- --- -------
----- -----------
--
-- -- -------------
----- ----- - ----------------------
-- -- ------- --
-------------------- ---------------- ------------------------在这里，我们首先定义了一些信息，如API的标题、版本、描述等。接着，我们配置了 API 的服务器信息。最后，我们使用 Swagger-jsdoc 创建 Swagger 规范，并将其传递给 Swagger UI 中间件的 setup() 方法。
步骤 3：启动应用程序
我们已经准备好了 Swagger 规范和 Swagger UI，现在只需启动我们的 Express 应用程序即可访问 Swagger UI。
---------------- -- -- - ------------------- ------- -- ---- ------- ---
现在如果你打开 http://localhost:3000/api-docs，你将看到一个漂亮的 Swagger UI，展示了我们的 API 文档和可交互式的操作。
示例代码
下面是完整的示例代码：
----- ------- - -------------------
----- ------------ - -------------------------
----- --------- - ------------------------------
----- --- - ----------
---
- --------
- -----------
- --------
- -----
- ---------
- - --------
- - -----
- -----------
- ---------
- ----- ------
- ------
- ----- ------
-
- -------
- ----
- -------- --- --- -----
- ------------ -------- - ---- -- --- ---------- -----
- ----------
- ------
- ------------ - ---------- --------
- --------
- -----------------
- -------
- ----- -----
- ------
- ----- ---------------------------
--
----- ------- - -
----------- -
-------- --------
----- -
------ ------ -----
-------- --------
------------ -- ------ --- -- --- --- ---------- -------
--
-------- -
-
---- -------------------------
--
--
--
----- -----------
--
----- ----- - ----------------------
-------------------- ---------------- ------------------------
---------------- -- -- -
------------------- ------- -- ---- -------
---结论
在本教程中，我们学习了如何在 Express.js 中集成 Swagger UI。我们了解了 Swagger 规范、Swagger-jsdoc 和 Swagger UI 的概念。既然我们已经集成了 Swagger UI，我们可以更轻松地为我们的 API 提供可交互的文档支持。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/6735460f0bc820c5824d7a18