什么是 RESTful API?
RESTful API 是一种设计风格，它使用 HTTP 请求来执行 CRUD 操作（创建、读取、更新、删除）并返回 JSON 格式的响应。RESTful API 是面向 Web 的 API，它是可缓存、可扩展、可靠、自描述、分层式的架构风格。
RESTful API 中的资源是以 URI（Uniform Resource Identifier，统一资源标识符）的形式暴露的。可以使用 HTTP 方法（GET、POST、PUT、DELETE）执行对资源的操作。
为什么需要 API 文档?
API 文档是用于记录和传达 API 的信息和用法的重要工具。API 文档可以使开发人员更快地理解如何使用 API，以及可以帮助他们遵循 API 的最佳实践。
当多个开发人员参与项目时，API 文档可以使它们之间更加协调。 API 文档在开发过程中也可以作为测试和验证的基础。API 文档应该包含有关 API 的特定细节，例如请求格式、响应格式、错误消息和可用参数。
什么是 Swagger?
Swagger 是一种用于编写 OpenAPI 规范的工具。OpenAPI 规范是用于创建和设计 RESTful API 的规范，它提供了一套标准，使得不管 API 的设计人员是谁都可以理解和使用。
Swagger 提供了用于生成和管理 API 文档的框架。它支持 RESTful API 的各种 HTTP 方法，并且可以生成 API 的响应模板。Swagger 可以根据 API 中定义的 RESTful 操作自动生成 API 文档。
如何使用 Swagger 自动生成 API 文档
Swagger 提供了一种用于自动生成 API 文档的简单方法。在这里，我们将使用 Node.js 和 Express 开发框架创建一个 RESTful API，并使用 Swagger 自动生成 API 文档。
安装依赖项
在使用 Swagger 自动生成 API 文档之前，我们需要确保已安装了以下依赖项：
- Node.js
- Express
- Swagger
使用以下命令安装 Swagger：
npm install -g swagger
创建 RESTful API
下面是一个简单的 RESTful API，可以用于演示如何使用 Swagger 自动生成 API 文档：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- --- - ---------- --------------------------- ----- ---- -- - ----- ---- - ---------------- ----- ------- - ------- ---------- ------------------------------ ---------- --- ---------------- -- -- ------------------- ------- -- ---- --------
在此代码中，我们使用 Express 创建了一个简单的 GET 请求，用于根据名称返回问候语。
添加 Swagger 到 RESTful API
在创建完我们的 RESTful API 之后，我们可以使用 Swagger 自动生成 API 文档。首先，我们需要在项目的根目录中创建一个 Swagger 规范文件，也称为 swagger.json。
swagger.json 中的内容如下所示：
-- -------------------- ---- -------
-
---------- ------
------- -
-------- -------- ---------
-------------- -- ------ --- ------------- ----- ---------
---------- -------
--
------- -----------------
----------- ----
---------- -
------
--
----------- -
------------------
--
----------- -
------------------
--
-------- -
-------------------- -
------ -
---------- -------- - -------- ---- --- ---- ----------
-------------- -------- - -------- ---- --- ---- ----------
------------- -
-
------- -------
----- -------
-------------- ---- ---- -- --- -- --- ----------
----------- -----
------- --------
-
--
------------ -
------ -
-------------- ----------- ----------
--------- -
------- ---------
------------- -
---------- -
------- --------
-
-
-
-
-
-
-
-
-在此 Swagger 规范文件中，我们定义了 API 的基本信息、主机名、基本路径、HTTP 方法、响应模板等。
将 Swagger 配置添加到 Node.js 应用程序
现在，我们需要将 Swagger 配置添加到 Node.js 应用程序中。我们可以创建一个新文件 swagger.js 并在其中编写以下代码：
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
module.exports = (app) => {
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
};在此代码中，我们将 swagger.json 文件导入为 swaggerDocument，并在 Express 应用程序上使用 Swagger-UI-Express 添加 Swagger 配置。这将启动 Swagger UI，其中包含自动生成的 API 文档。
我们需要修改我们之前的代码，以便将 Swagger 配置添加到 REST API 中。我们可以更新 REST API 代码以添加以下几行：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- --- - ---------- ----- ------------- - --------------------- ------------------- --------------------------- ----- ---- -- - ----- ---- - ---------------- ----- ------- - ------- ---------- ------------------------------ ---------- --- ---------------- -- -- ------------------- ------- -- ---- --------
在这些代码中，我们使用 swaggerConfig 函数在 Node.js 应用程序中引入 Swagger 配置。然后，我们将之前的内容添加回使用 express 创建的代码中。
验证 API 文档
使用 Swagger 自动生成 API 文档是一个好习惯，不仅可以改进 API 开发体验，还可以帮助团队协作、提高代码质量。
现在，我们可以通过访问 https://localhost:3000/docs，来验证我们生成的 Swagger API 文档。
总结
Swagger 是一款帮助我们设计和生成 RESTful API 的工具。使用 Swagger 我们可以更好地管理 API 文档，并且让整个团队更好地协作。
本文介绍了如何使用 Swagger 自动生成 API 文档。首先，我们创建了一个简单的 RESTful API，然后使用 Swagger 生成了相应的 API 文档。最后，我们将 Swagger 添加到 Node.js 应用程序中以启动自动生成的 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6457439e968c7c53b0a0a336