介绍
OpenAPI 3.0 是一个用于描述 RESTful API 的规范，它可以用于描述 API 的请求和响应格式、参数、路径等等。openapi3-middleware 是一个可以使用 OpenAPI 3.0 规范验证和格式化请求和响应的 Express 中间件。
安装
使用 npm 安装 openapi3-middleware：
npm install openapi3-middleware --save
使用
配置
首先需要在项目中定义一个 OpenAPI 3.0 规范的文件（通常是一个 YAML 或 JSON 文件）。在这个文件中，我们定义了 API 路径、请求和响应的格式、参数等信息。
然后在 Express 应用中使用 openapi3-middleware，将这个规范文件传递给中间件，并配置一些选项：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ----------------- - ------------------------------- ----- --- - ---------- ----- ------- - --------------------------- ----- ------- - - ------------------ ----- -- -------- ------------ ----- -- ---------------------------- --------------- --------- -- ------------------------ -- ---------------------------------- ----------
使用 app.use(openapiMiddleware(apiSpec, options)) 将 openapi3-middleware 加入到我们的 Express 应用中，其中 apiSpec 是我们定义的 OpenAPI 3.0 规范文件，options 是可选的选项。
验证请求和响应
当中间件收到一个请求时，会首先验证该请求是否符合规范中定义的路径、参数等信息。如果不符合规范，则返回一个包含错误信息的响应。
当服务器产生一个响应时，中间件会验证该响应是否符合规范中定义的状态码、响应体等信息。如果不符合规范，则返回一个包含错误信息的响应。
示例
我们假设我们有一个 API，包含一个 /user 路径，当它接到一个 POST 请求时会创建一个新的用户。我们可以通过 OpenAPI 3.0 规范定义这个 API 的请求和响应：
-- -------------------- ---- -------
-------- -----
-----
------ -- ---
-------- -----
------
-------
-----
------------
--------- ----
--------
-----------------
-------
----- ------
-----------
-----
----- ------
----------
----
------------ ---- ------- ------------然后我们使用 openapi3-middleware 在应用中加入中间件，并使用上面定义的规范文件：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ----------------- - ------------------------------- ----- --- - ---------- ----- ------- - --------------------------- ----- ------- - - ------------------ ----- ------------ ----- --------------- --------- -- ------------------------ ---------------------------------- ---------- ------------------ ----- ---- -- - ----- - ---- - - --------- -- -------- -------------- ------- --------------- ---
现在我们就可以访问 API 来创建用户了：
POST /users
Content-Type: application/json
{
"name": "Alice"
}如果请求体不符合定义的格式，将返回一个包含错误信息的响应：
-- -------------------- ---- -------
-------- --- --- -------
------------- ----------------
-
--------- -
-
------- --------
---------- ------- -- -------
-
-
-如果响应不符合定义的格式，将返回一个包含错误信息的响应：
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": 123
}将返回：
-- -------------------- ---- -------
-------- --- -------- ------ -----
------------- ----------------
-
--------- -
-
------- --------
---------- ------- -- -------
-
-
-总结
openapi3-middleware 是一个非常有用的 Express 中间件，可以用于验证和格式化 API 的请求和响应。通过定义 OpenAPI 3.0 规范文件并使用中间件，我们可以更好地保证 API 的正确性和可维护性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6006734a890c4f7277583741