Swagger 是一种用于描述 RESTful API 的标准。在使用 RESTful API 进行开发的过程中，我们通常需要编写大量的文档来描述 API。而 Swagger 的出现，则使得我们可以用一个简单的文件来描述 API，并且还提供了自动生成 API 文档的工具。
@apidevtools/swagger-parser 是一个 Swagger 风格的 API 描述工具，它可以读取 Swagger API 描述，解析其中的所有内容，并将其转为可读的 JSON 格式，方便进一步的处理。本篇文章将详细介绍如何使用 @apidevtools/swagger-parser 包来解析 Swagger 描述文件，并使用其提供的 API 来访问其中的信息。
安装
首先，我们需要安装 @apidevtools/swagger-parser 包。可以使用以下命令安装：
npm install @apidevtools/swagger-parser
解析 Swagger API 描述
@apidevtools/swagger-parser 提供了许多 API 来读取 Swagger API 描述。其中，最为重要的两个 API 分别是 parse() 和 validate()。其中，parse() 函数用于解析 Swagger API 描述文件，并返回一个 JavaScript 对象，该对象包含了所有的 API 信息。而 validate() 函数则用于验证 Swagger API 描述文件是否符合 Swagger 定义的规范。
为了演示如何使用 @apidevtools/swagger-parser，我们将使用 Swagger 官方提供的 Petstore 示例 API。该 API 的 Swagger 描述文件可以在以下链接找到：
https://petstore.swagger.io/v2/swagger.json
我们可以使用以下代码来获取该 API 的描述信息：
const SwaggerParser = require("@apidevtools/swagger-parser");
SwaggerParser.parse("https://petstore.swagger.io/v2/swagger.json").then((api) => {
console.log(api);
}, (err) => {
console.error(err);
});运行以上代码，输出结果如下：
-- -------------------- ---- -------
-
-------- ------
----- -
------ -------- ----------
-------- -------
--
----- ----------------------
--------- ------
-------- - ------- ------- --
--------- - ------------------ --
--------- - ------------------- ----------------- --
------ -
------- -
----- -
----- --------
-------- ---- - --- --- -- --- -------
------------ ---
------------ ---------
--------- --------
--------- --------
----------- --------
---------- --------
-
--
---
--
------------ - --- --
----------- - --- --
---------- - --- --
-------------------- - --- --
----- - --- --
------------- - --- -
-我们可以看到，解析得到的对象包含了 API 的基本信息，包括版本号、主机地址、基础路径、以及每一个 API 的具体描述信息。接下来，我们将详细介绍如何使用这些信息来开发应用程序。
使用 JSONPath
JSONPath 是一种类似于 XPath 的 JSON 路径描述语言，可以使用该语言来查询 JSON 对象中的数据。SwaggerParser 包提供了内置的 JSONPath 实现，因此我们可以使用 JSONPath 来方便地查询 API 描述信息。
例如，我们可以使用以下代码来查询 Petstore API 中所有方法的名字：
const SwaggerParser = require("@apidevtools/swagger-parser");
SwaggerParser.parse("https://petstore.swagger.io/v2/swagger.json").then((api) => {
const methodNames = SwaggerParser.JSONPath.query(api, "$..operationId");
console.log(methodNames);
}, (err) => {
console.error(err);
});输出结果如下：
-- -------------------- ---- ------- - --------- ------------ ------------------- ----------------- ------------- -------------------- ------------ ------------- --------------- ------------- --------------- -------------- ------------- ---------------------------- --------------------------- ------------ ------------- ---------------- ------------- ------------ -
我们可以看到，得到了所有方法的名字。
除了可以查询 API 描述信息之外，JSONPath 还可以用来对 API 描述信息进行修改，删除和替换等操作。更多关于 JSONPath 的信息可以参考 JSONPath 官方文档。
在 Express 中使用 API
@apidevtools/swagger-parser 还提供了 express-ajv-swagger-validation 插件，可以用于在 Express 中自动验证 API 请求和响应的数据格式是否符合 Swagger 描述文件定义的规范。使用该插件的步骤如下：
- 将 @apidevtools/swagger-parser 安装到依赖中
- 定义 Swagger 描述文件
- 在 Express 中注册 express-ajv-swagger-validation 插件，并指定 Swagger 描述文件的路径
以下是使用 express-ajv-swagger-validation 的示例代码：
-- -------------------- ---- -------
----- ------- - -------------------
----- ------------- - ---------------------------------------
----- ----------------- - ------------------------------------------
----- --- - ----------
------------------------------------------------- -- -
--------------------------------------------- -------
-- ----- -- -
-------------------
---
----------------- ----- ---- -- -
-- ------- -------- ---- ------- ---------
----------
------- ----------
----- --------
---
---
---------------- -- -- -
------------------- ------- -- ---- -------
---此时，当我们向 /pets 接口发送一个 JSON 格式的请求体时，如果请求体不符合 Swagger 描述文件定义的格式，服务器将会自动返回一个 400 错误。
总结
使用 @apidevtools/swagger-parser 包可以轻松地解析 Swagger 描述文件，并且可以方便地使用 JSONPath 查询或修改 API 描述信息。同时，结合 express-ajv-swagger-validation 插件，我们可以自动验证 API 请求和响应的格式是否合规，并及时发现问题，提高 API 开发的效率和质量。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedb0c5b5cbfe1ea06110e7