前言
OpenAPI 是一种描述 RESTful API 的规范，使得我们在设计和实现 API 时能够更加一致和有效地描述 RESTful API 的结构，以便于开发者构建 API 客户端或者服务端。在 OpenAPI 规范中，定义了 request、response、schema 等内容。由于 OpenAPI 规范促进了 API 的标准化，因此越来越多的团队加入了 OpenAPI 规范的阵营。但是，当 OpenAPI 提供更多额外的功能和校验时，不可避免会有不少的 schema 需要我们管理和维护。于是，npm 包 @apidevtools/openapi-schemas 打包来应对这样的需求。它是一个 JSON Schema 工具集，在 OpenAPI 规范下，可以用于定义和验证 JSON 文档的结构。本篇文章，将会介绍此 npm 包的详细使用方法。
安装
npm install @apidevtools/openapi-schemas --save
API 详解
OpenAPI Schemas
OpenAPI Schemas 通过多个 JSON Schema 文件来描述 OpenAPI 规范提供的结构，以便于开发者验证 API 定义和对其采取相应的行动。
import { OpenAPISchemas } from "@apidevtools/openapi-schemas";
schemas
schemas 是一个对象，它包含了每个 JSON 文件中从 $ref 中导入的所有 schemas 。导入哪些 schemas 取决于 $ref，可以通过传递 options.loaders 配置项来自定义其解析方式。 schemas 使用 ijsonschema 作为规范模式的元数据验证实例，以及 ref-parser 解析库，并通过 json schema 中的 ref 属性来嵌套处理验证实例。可以通过 options 来设置 schemas 中的如下值：
allowUnknownKeywords：是否允许未知的关键字 (default istrue)allowUnusedKeywords：是否允许未使用的关键字 (default isfalse)allowDeprecatedKeywords：是否允许使用弃用的关键字 (default isfalse)
const schemas = OpenAPISchemas.create(); // creates an empty schema collection schemas.loadFile("path/to/openapi.yaml"); // loads the specified file schemas.loadFiles("path/to/**/*.json"); // loads all JSON files in the specified directory and subdirectories schemas.addSchema("mySchema", { type: "string" }); // adds a schema directly, without loading a file
validateSchema(content: SchemaObject): boolean
使用此方法验证传入的 JSON 内容是否遵循 JSON Schema 式的 API 规范，如果验证通过，则返回 true，否则返回 false。
-- -------------------- ---- ------- ------ - -------------- - ---- ------------------------------- ----- ------- - - ----- --------- ----------- - ----- - ----- --------- -- ---- - ----- ---------- -- -- --------- --------- -- ----- ------- - ----------------------- --------------------- -- ----展开代码
resolve(schema: any, strict = false): Promise<any>
使用此方法，可以将指定 JSON 模式的 $ref 指向本地 URL 或网址已解析的对象的内联模式。将 strict 参数设置为 true，将强制在解析时强制验证所有模式。返回的 Promise 将解析模式，所有 $ref 指向的模式和所有自定义关键字并返回结果。
-- -------------------- ---- ------- ------ - ------- - ---- ------------------------------- ----- ------ - - ----- ------------------------------------- -- --------------------------- -- - -- -------- ------ -- -------- ---展开代码
validate(data: any, schema: any): ValidationError[]
这个方法根据指定的模式验证某个 json。如果遇到任何错误，则返回一个包含 ValidationError 实例的数组。ValidationError 实例将包含错误消息、上下文和其他详细信息。
-- -------------------- ---- ------- ------ - -------- - ---- ------------------------------- ----- ------ - - ----- --------- ----------- - ----- - ----- --------- -- ---- - ----- ---------- -- -- --------- --------- -- ----- ---- - - ----- ----- ----- ---- --- -- ----- ------ - -------------- -------- --------- -- -------------- - ----------------------- --------- -------- - ---- - ----------------------- --------- -展开代码
ValidationError
ValidationError 是一个可以表达用来描述 validate 方法返回错误信息的对象，构造简单，但传递的参数非常明确。
-- -------------------- ---- ------- ------ - --------------- - ---- ------------------------------- -- ------ ----------- ----- --------------- - --- ------------------------ ------- - -------- ---- -------- -- --------------------- -- ----------- ---- --------- ----- ------- - --- ------------------------------- ------ --------- --------------------- ------------------------------- -- -------------- ----------------------------- -- ------ -------- ------------------------------ -- -------------------展开代码
ValidationOptions
ValidationOptions 是一个可以用来更进一步简化 schema 验证的函数。
-- -------------------- ---- ------- ------ - --------------- -------- - ---- ------------------------------- ----- ------ - - ----- --------- ----------- - ----- - ----- --------- -- ---- - ----- ---------- -- -- --------- --------- -- ----------------------- -- ---- ------ ---- ------- --- ------ -- ----- ----- ---- - - ----- ----- ----- ---- --- -- ----- ----------------- - - ----------- ------ ---------------- ----- -- ----- ------- - -------------- ------- ------------------ --------------------- -- ----展开代码
以上内容便是 @apidevtools/openapi-schemas 所提供的方法，其中包括 schemas、validateSchema、resolve、validate 和 ValidationError。这个工具不仅适用于 node.js 项目，也可以用于浏览器端的开发中。下面，将结合实际场景，来演示简单的使用方式。
示例
示例运行前需要先安装 node-fetch 和 yaml-parser 两个包。开一个新的目录，然后实现以下的代码：
首先新建
src目录，然后在该目录下新建 server.yaml 文件，内容如下：-- -------------------- ---- ------- -------- ------- ----- ------ -------- --------- ------------ -- ------ --- ---- ---- - -------- -- -- -------- -------- ------- ------ ------ ---- -------- ----- --- ----- ------------ ---------- ----- - ------ ----------- - ----- ------- --- ------- ------------ ---- ---- ----- -- ------ -- --- ---- ---- ----- --------- ----- ------- ----- --------- ------- ------- -------- - -------- --- ---------- ------ ------------ -- ----- ----- -- ----- -------- ------- ------------ -- ---- -- --- ---- ---- -- ---------- ------- ----- -------- -------- ----------------- ------- ----- --------------------------- ----------- ---- -------- ----- --- - -------- ---- ------------ ------------- ----- - ------ ----------- - ----- ---- --- ------ --------- ---- ------------ ---- -- -- --- --- -- --------- ------- ----- -------- ---------- ------ ------------ --------- -------- -- - ----- -------- -------- ----------------- ------- ----- -------------------------- ------- -------- -------- - ---- ------------ ----------- ----- - ------ ----------- - ----- --------- --- -------- --------- ----- ------- ----- -------- - ----- ---- --- ------ --------- ---- ------- ----- --------- ---------- ------ ------------ -------- -- --------- ------ ------------ ---- --- ------ ----------- -------- ---- ----- -------- --------- - ---- - ------ ----------- --- ----- --------- ------- ------- ----- ----- -------- ---- ----- -------- ----- ----- ------- ------ ----- --------------------------
展开代码新建 index.js 文件，使用
node-fetch和yaml-parser来获取 server.yaml 并进行校验。-- -------------------- ---- ------- ------ ----- ---- ------------- ------ - ----- - ---- ------- ------ - --------------- -------------- - ---- ------------------------------- ----- -------- ---------------- - ----- -------- - ----- ------------------------------------------- ----- ---- - ----- ---------------- ----- ------ - ------------ ----- ------- - ----------------------- -- ---------- - --------------------- ------ ---------- ------- - ------------------- ------ -- -------- - -----------------
展开代码在终端下输入
node index.js，输出：Server schema is valid。
以上代码，使用 @apidevtools/openapi-schemas 对 server.yaml 的内容进行了校验，因此也能够运用在其他项目中。同时，它也具有很高的指导意义：使用 OpenAPI 和 JSON Schema 规范，能够使得我们更好地构建和解析 API，也能够规范化我们的 API 定义，让我们的项目更完善和严谨。
小结
本文为大家详细介绍了 npm 包 @apidevtools/openapi-schemas 的使用方式和 API。这个 npm 包使用 JSON Schema 工具集，提供了一种方便和高效的方式，用于定义和验证 JSON 文档的结构。如果你经常使用和构建 Web API，那么这个工具可能是你需要的。希望本篇文章能够为你提供帮助，感谢阅读！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5f329c2edbf7be33b2566dad
