Swagger UI 是一个流行的 API 文档生成工具，具有交互式界面和代码生成功能。Node.js 是一种跨平台的 JavaScript 运行环境，广泛用于构建高性能的 Web 应用程序。
本文将介绍如何使用 Swagger UI 和 Node.js 构建 RESTful API，包括如何在项目中集成 Swagger UI，编写 RESTful API，并使用 Swagger UI 自动生成 API 文档和代码。
什么是 RESTful API
RESTful API 是一种 Web API 设计模式，旨在通过标准化的方式提供数据和功能。它是 Representational State Transfer（表述性状态转移）的缩写，定义了一组规范和约定，包括使用 HTTP 方法（GET、POST、PUT、DELETE、PATCH 等），资源标识符（URI），以及数据格式（JSON、XML 等）等。
Swagger UI
Swagger UI 是一个开源工具，用于生成和显示 API 文档，让 API 的使用者可以方便地了解和测试 API，同时还支持生成客户端代码。Swagger UI 有以下几个主要特点：
- 能够自动生成 API 文档。
- 提供交互式的测试界面。
- 支持多种 API 规范，如 OpenAPI（前身为 Swagger）、RAML、API Blueprint 等。
- 支持多种语言的客户端代码生成。
在 Node.js 项目中使用 Swagger UI，首先需要安装 swagger-ui-express 和 swagger-jsdoc 两个 npm 包。
npm install swagger-ui-express swagger-jsdoc --save
然后，创建一个 app.js 文件，使用以下代码初始化 Express 应用程序，并告诉应用程序使用 Swagger UI 显示 API 文档。
-- -------------------- ---- -------
----- ------- - -------------------
----- --------- - ------------------------------
----- ------------ - -------------------------
----- --- - ----------
----- -------------- - -
------------------ -
-------- --------
----- -
------ --- -----
-------- --------
------------ --- --- -------------
--
-------- -
- ---- ------------------------ ------------ ------------ ------- --
--
--
----- ------------
--
----- ----------- - -----------------------------
-------------------- ---------------- ------------------------------
---------------- -- -- -
---------------------- -- ---- -------
---以上代码使用 swagger-jsdoc 生成 API 文档，并使用 swagger-ui-express 显示文档。其中，swaggerOptions 配置中定义了 API 的基本信息和接口的地址和描述，apis 属性指定了需要生成文档的文件。在应用程序中需要使用注释的方式编写 API 文档。例如，在一个 sample.js 文件中，写以下代码。
-- -------------------- ---- -------
---
- --------
- -----------
- --------
- -------
- ----- ------
- -----------
- ---
- ----- -------
- -----
- ----- ------
--
---
- --------
- ---------
- ----
- -------- ---- --- -------
- ------------ -------- - ---- -- -------
- -----
- - ------
- ----------
- ------
- ------------ - ---- -- --------
- --------
- -----------------
- -------
- ----- -----
- ------
- ----- -----------------------------
--
------------------- ----- ---- -- -
----- ------- - -
- --- -- ----- ------- -- --
- --- -- ----- ------- -- --
--
------------------
---在以上代码中，使用注释的方式显式编写了样本的描述和 GET 请求的描述，并给出了响应示例和元数据格式。这些注释中的内容会被 swagger-jsdoc 解析，用于生成 API 文档。
Node.js RESTful API
为了演示 Node.js 的 RESTful API，我们将创建一个 Todo 应用程序，支持以下操作：
- 获取所有的 Todo。
- 根据 ID 获取指定的 Todo。
- 创建一个新的 Todo。
- 更新指定 Todo 的完成状态。
- 根据 ID 删除指定的 Todo。
以上操作将使用 HTTP 方法 GET、POST、PUT 和 DELETE，以及 Todo 的 ID、标题和完成状态等数据。
首先，创建一个名为 todo.js 的文件，定义以下内容：
-- -------------------- ---- -------
----- ------- - -------------------
----- ---------- - -----------------------
----- ---- - ----------------
----- --- - ----------
---------------------------
------------------------------- --------- ---- ----
----------------
--- ----- - -
- --- -- ------ ----- --- ---------- ----- --
- --- -- ------ ----- --- ---------- ----- --
--
----------------- ----- ---- -- -
----------------
---
--------------------- ----- ---- -- -
----- -- - ------------------------
----- ---- - ----------------- -- ------- --- ----
-- ------ -
---------------
- ---- -
-----------------------
-
---
------------------ ----- ---- -- -
----- ---- - ---------
------- - ------------ - --
-----------------
---------------------------
---
--------------------- ----- ---- -- -
----- -- - ------------------------
----- ---- - ----------------- -- ------- --- ----
-- ------ -
-------------- - ------------------ -- ---------------
---------------
- ---- -
-----------------------
-
---
------------------------ ----- ---- -- -
----- -- - ------------------------
----- --------- - ---------------------- -- ------- --- ----
-- ---------- - --- -
----------------------- ---
-----------------------
- ---- -
-----------------------
-
---
---------------- -- -- -
---------------------- -- ---- -------
---在以上代码中，我们创建了一个 Express 应用程序，使用 bodyParser 中间件来解析请求主体，cors 中间件允许跨源请求，然后定义了 GET、POST、PUT 和 DELETE 等方法来处理 Todo 数据的操作。在应用程序中，todos 变量存储了 Todo 数据。
Swagger UI 自动生成 RESTful API 文档和代码
在以上两个代码示例中，我们已经演示了如何使用 Swagger UI 和 Node.js 分别创建 RESTful API 和 API 文档。使用 Swagger UI 还可以方便地生成客户端代码，减少手写代码的量。例如，生成 JavaScript 客户端代码，可以通过以下命令（需要安装 Swagger Codegen）：
swagger-codegen generate \ -i http://localhost:3000/api-docs.json \ -l javascript --output-dir petstore-client
这将自动生成一个名为 petstore-client 的目录，包含用于调用 RESTful API 的 JavaScript 文件。这些文件使用 Ajax 发送 HTTP 请求，并返回从服务器响应的数据。
在实际项目中，Swagger UI 和 Node.js 牵涉到的细节和内容比这个简单的示例更加复杂。但是，这个例子可以作为学习 Swagger UI 和 Node.js 中 RESTful API 编写的基础。建议在开发前，先学习 API 设计的基本原则，再对 Swagger UI 和 Node.js 的使用进行深入学习。
Source: FunTeaLearn,Please indicate the source for reprints https://funteas.com/post/67cf57cee46428fe9ea7edc1