@speclynx/apidom-ns-openapi-3-1 1.12.1

package/src/refractor/plugins/normalize-parameters.cjs

@@ -0,0 +1,103 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-0");
+var _NormalizeStorage = _interopRequireDefault(require("./normalize-header-examples/NormalizeStorage.cjs"));
+/**
+ * Inheritance of Parameter Objects.
+ *
+ * OpenAPI 3.1 specification excerpt that defines the inheritance behavior:
+ *
+ * A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item,
+ * the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters.
+ * A unique parameter is defined by a combination of a name and location.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  /**
+   * Establishes identity between two Parameter Objects.
+   *
+   * {@link https://spec.openapis.org/oas/v3.1.2.html#operation-parameters}
+   */
+  const parameterEquals = (parameter1, parameter2) => {
+    if (!predicates.isParameterElement(parameter1)) return false;
+    if (!predicates.isParameterElement(parameter2)) return false;
+    if (!predicates.isStringElement(parameter1.name)) return false;
+    if (!predicates.isStringElement(parameter1.in)) return false;
+    if (!predicates.isStringElement(parameter2.name)) return false;
+    if (!predicates.isStringElement(parameter2.in)) return false;
+    return (0, _apidomCore.toValue)(parameter1.name) === (0, _apidomCore.toValue)(parameter2.name) && (0, _apidomCore.toValue)(parameter1.in) === (0, _apidomCore.toValue)(parameter2.in);
+  };
+  const pathItemParameters = [];
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(element) {
+          storage = new _NormalizeStorage.default(element, storageField, 'parameters');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      PathItemElement: {
+        enter(pathItemElement, key, parent, path, ancestors) {
+          // skip visiting this Path Item
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+          const {
+            parameters
+          } = pathItemElement;
+          if (predicates.isArrayElement(parameters)) {
+            pathItemParameters.push([...parameters.content]);
+          } else {
+            pathItemParameters.push([]);
+          }
+        },
+        leave() {
+          pathItemParameters.pop();
+        }
+      },
+      OperationElement: {
+        leave(operationElement, key, parent, path, ancestors) {
+          const parentPathItemParameters = (0, _ramda.last)(pathItemParameters);
+
+          // no Path Item Object parameters to inherit from
+          if (!Array.isArray(parentPathItemParameters) || parentPathItemParameters.length === 0) {
+            return;
+          }
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+          const operationParameters = (0, _ramda.pathOr)([], ['parameters', 'content'], operationElement);
+
+          // prefers the first item if two items compare equal based on the predicate
+          const mergedParameters = (0, _ramda.uniqWith)(parameterEquals, [...operationParameters, ...parentPathItemParameters]);
+          operationElement.parameters = new _apidomNsOpenapi.OperationParametersElement(mergedParameters);
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+var _default = exports.default = plugin;

package/src/refractor/plugins/normalize-parameters.mjs

@@ -0,0 +1,97 @@
+import { uniqWith, pathOr, last } from 'ramda';
+import { toValue } from '@speclynx/apidom-core';
+import { OperationParametersElement } from '@speclynx/apidom-ns-openapi-3-0';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
+/**
+ * Inheritance of Parameter Objects.
+ *
+ * OpenAPI 3.1 specification excerpt that defines the inheritance behavior:
+ *
+ * A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item,
+ * the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters.
+ * A unique parameter is defined by a combination of a name and location.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  /**
+   * Establishes identity between two Parameter Objects.
+   *
+   * {@link https://spec.openapis.org/oas/v3.1.2.html#operation-parameters}
+   */
+  const parameterEquals = (parameter1, parameter2) => {
+    if (!predicates.isParameterElement(parameter1)) return false;
+    if (!predicates.isParameterElement(parameter2)) return false;
+    if (!predicates.isStringElement(parameter1.name)) return false;
+    if (!predicates.isStringElement(parameter1.in)) return false;
+    if (!predicates.isStringElement(parameter2.name)) return false;
+    if (!predicates.isStringElement(parameter2.in)) return false;
+    return toValue(parameter1.name) === toValue(parameter2.name) && toValue(parameter1.in) === toValue(parameter2.in);
+  };
+  const pathItemParameters = [];
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(element) {
+          storage = new NormalizeStorage(element, storageField, 'parameters');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      PathItemElement: {
+        enter(pathItemElement, key, parent, path, ancestors) {
+          // skip visiting this Path Item
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+          const {
+            parameters
+          } = pathItemElement;
+          if (predicates.isArrayElement(parameters)) {
+            pathItemParameters.push([...parameters.content]);
+          } else {
+            pathItemParameters.push([]);
+          }
+        },
+        leave() {
+          pathItemParameters.pop();
+        }
+      },
+      OperationElement: {
+        leave(operationElement, key, parent, path, ancestors) {
+          const parentPathItemParameters = last(pathItemParameters);
+
+          // no Path Item Object parameters to inherit from
+          if (!Array.isArray(parentPathItemParameters) || parentPathItemParameters.length === 0) {
+            return;
+          }
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+          const operationParameters = pathOr([], ['parameters', 'content'], operationElement);
+
+          // prefers the first item if two items compare equal based on the predicate
+          const mergedParameters = uniqWith(parameterEquals, [...operationParameters, ...parentPathItemParameters]);
+          operationElement.parameters = new OperationParametersElement(mergedParameters);
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+export default plugin;

package/src/refractor/plugins/normalize-security-requirements.cjs

@@ -0,0 +1,71 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-0");
+var _NormalizeStorage = _interopRequireDefault(require("./normalize-header-examples/NormalizeStorage.cjs"));
+/**
+ * Override of Security Requirement Objects.
+ *
+ * OpenAPI 3.1 specification excerpt that defines the override behavior:
+ *
+ * Operation.security definition overrides any declared top-level security.
+ * To remove a top-level security declaration, an empty array can be used.
+ * When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object,
+ * only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let topLevelSecurity;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(openapiElement) {
+          storage = new _NormalizeStorage.default(openapiElement, storageField, 'security-requirements');
+          if (predicates.isArrayElement(openapiElement.security)) {
+            topLevelSecurity = openapiElement.security;
+          }
+        },
+        leave() {
+          storage = undefined;
+          topLevelSecurity = undefined;
+        }
+      },
+      OperationElement: {
+        leave(operationElement, key, parent, path, ancestors) {
+          // skip visiting this Operation
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+          const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
+          const hasTopLevelSecurity = typeof topLevelSecurity !== 'undefined';
+          if (missingOperationLevelSecurity && hasTopLevelSecurity) {
+            operationElement.security = new _apidomNsOpenapi.OperationSecurityElement(topLevelSecurity?.content);
+            storage.append(operationJSONPointer);
+          }
+        }
+      }
+    }
+  };
+};
+var _default = exports.default = plugin;

package/src/refractor/plugins/normalize-security-requirements.mjs

@@ -0,0 +1,65 @@
+import { OperationSecurityElement } from '@speclynx/apidom-ns-openapi-3-0';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
+/**
+ * Override of Security Requirement Objects.
+ *
+ * OpenAPI 3.1 specification excerpt that defines the override behavior:
+ *
+ * Operation.security definition overrides any declared top-level security.
+ * To remove a top-level security declaration, an empty array can be used.
+ * When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object,
+ * only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let topLevelSecurity;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(openapiElement) {
+          storage = new NormalizeStorage(openapiElement, storageField, 'security-requirements');
+          if (predicates.isArrayElement(openapiElement.security)) {
+            topLevelSecurity = openapiElement.security;
+          }
+        },
+        leave() {
+          storage = undefined;
+          topLevelSecurity = undefined;
+        }
+      },
+      OperationElement: {
+        leave(operationElement, key, parent, path, ancestors) {
+          // skip visiting this Operation
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+          const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
+          const hasTopLevelSecurity = typeof topLevelSecurity !== 'undefined';
+          if (missingOperationLevelSecurity && hasTopLevelSecurity) {
+            operationElement.security = new OperationSecurityElement(topLevelSecurity?.content);
+            storage.append(operationJSONPointer);
+          }
+        }
+      }
+    }
+  };
+};
+export default plugin;

package/src/refractor/plugins/normalize-servers.cjs

@@ -0,0 +1,118 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-0");
+var _NormalizeStorage = _interopRequireDefault(require("./normalize-header-examples/NormalizeStorage.cjs"));
+/**
+ * Override of Server Objects.
+ *
+ * List of Server Objects can be defined in OpenAPI 3.1 on multiple levels:
+ *
+ *  - OpenAPI.servers
+ *  - PathItem.servers
+ *  - Operation.servers
+ *
+ * If a servers array is specified at the OpenAPI Object level, it will be overridden by `PathItem`.servers.
+ * If a servers array is specified at the Path Item Object or OpenAPI Object level, it will be overridden by Operation.servers.
+ * @public
+ */
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    namespace,
+    ancestorLineageToJSONPointer,
+    predicates
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(openapiElement) {
+          const isServersUndefined = typeof openapiElement.servers === 'undefined';
+          const isServersArrayElement = predicates.isArrayElement(openapiElement.servers);
+          const isServersEmpty = isServersArrayElement && openapiElement.servers.length === 0;
+          // @ts-ignore
+          const defaultServer = namespace.elements.Server.refract({
+            url: '/'
+          });
+          if (isServersUndefined || !isServersArrayElement) {
+            openapiElement.servers = new _apidomNsOpenapi.ServersElement([defaultServer]);
+          } else if (isServersArrayElement && isServersEmpty) {
+            openapiElement.servers.push(defaultServer);
+          }
+          storage = new _NormalizeStorage.default(openapiElement, storageField, 'servers');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      PathItemElement(pathItemElement, key, parent, path, ancestors) {
+        // skip visiting this Path Item
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+        const pathItemJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, pathItemElement]);
+
+        // skip visiting this Path Item Object if it's already normalized
+        if (storage.includes(pathItemJSONPointer)) {
+          return;
+        }
+        const parentOpenapiElement = ancestors.find(predicates.isOpenApi3_1Element);
+        const isServersUndefined = typeof pathItemElement.servers === 'undefined';
+        const isServersArrayElement = predicates.isArrayElement(pathItemElement.servers);
+        const isServersEmpty = isServersArrayElement && pathItemElement.servers.length === 0;
+
+        // duplicate OpenAPI.servers into this Path Item object
+        if (predicates.isOpenApi3_1Element(parentOpenapiElement)) {
+          const openapiServersContent = parentOpenapiElement.servers?.content;
+          const openapiServers = openapiServersContent ?? [];
+          if (isServersUndefined || !isServersArrayElement) {
+            pathItemElement.servers = new _apidomNsOpenapi.PathItemServersElement(openapiServers);
+          } else if (isServersArrayElement && isServersEmpty) {
+            openapiServers.forEach(server => {
+              pathItemElement.servers.push(server);
+            });
+          }
+          storage.append(pathItemJSONPointer);
+        }
+      },
+      OperationElement(operationElement, key, parent, path, ancestors) {
+        // skip visiting this Operation
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+        const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+        // skip visiting this Operation Object if it's already normalized
+        if (storage.includes(operationJSONPointer)) {
+          return;
+        }
+
+        // @TODO(vladimir.gorej@gmail.com): can be replaced by Array.prototype.findLast in future
+        const parentPathItemElement = [...ancestors].reverse().find(predicates.isPathItemElement);
+        const isServersUndefined = typeof operationElement.servers === 'undefined';
+        const isServersArrayElement = predicates.isArrayElement(operationElement.servers);
+        const isServersEmpty = isServersArrayElement && operationElement.servers.length === 0;
+        if (predicates.isPathItemElement(parentPathItemElement)) {
+          const pathItemServersContent = parentPathItemElement.servers?.content;
+          const pathItemServers = pathItemServersContent ?? [];
+          if (isServersUndefined || !isServersArrayElement) {
+            // duplicate parent PathItem.servers into this Operation object
+            operationElement.servers = new _apidomNsOpenapi.OperationServersElement(pathItemServers);
+          } else if (isServersArrayElement && isServersEmpty) {
+            pathItemServers.forEach(server => {
+              operationElement.servers.push(server);
+            });
+          }
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+var _default = exports.default = plugin;

package/src/refractor/plugins/normalize-servers.mjs

@@ -0,0 +1,112 @@
+import { PathItemServersElement, OperationServersElement, ServersElement } from '@speclynx/apidom-ns-openapi-3-0';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
+/**
+ * Override of Server Objects.
+ *
+ * List of Server Objects can be defined in OpenAPI 3.1 on multiple levels:
+ *
+ *  - OpenAPI.servers
+ *  - PathItem.servers
+ *  - Operation.servers
+ *
+ * If a servers array is specified at the OpenAPI Object level, it will be overridden by `PathItem`.servers.
+ * If a servers array is specified at the Path Item Object or OpenAPI Object level, it will be overridden by Operation.servers.
+ * @public
+ */
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    namespace,
+    ancestorLineageToJSONPointer,
+    predicates
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(openapiElement) {
+          const isServersUndefined = typeof openapiElement.servers === 'undefined';
+          const isServersArrayElement = predicates.isArrayElement(openapiElement.servers);
+          const isServersEmpty = isServersArrayElement && openapiElement.servers.length === 0;
+          // @ts-ignore
+          const defaultServer = namespace.elements.Server.refract({
+            url: '/'
+          });
+          if (isServersUndefined || !isServersArrayElement) {
+            openapiElement.servers = new ServersElement([defaultServer]);
+          } else if (isServersArrayElement && isServersEmpty) {
+            openapiElement.servers.push(defaultServer);
+          }
+          storage = new NormalizeStorage(openapiElement, storageField, 'servers');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      PathItemElement(pathItemElement, key, parent, path, ancestors) {
+        // skip visiting this Path Item
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+        const pathItemJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, pathItemElement]);
+
+        // skip visiting this Path Item Object if it's already normalized
+        if (storage.includes(pathItemJSONPointer)) {
+          return;
+        }
+        const parentOpenapiElement = ancestors.find(predicates.isOpenApi3_1Element);
+        const isServersUndefined = typeof pathItemElement.servers === 'undefined';
+        const isServersArrayElement = predicates.isArrayElement(pathItemElement.servers);
+        const isServersEmpty = isServersArrayElement && pathItemElement.servers.length === 0;
+
+        // duplicate OpenAPI.servers into this Path Item object
+        if (predicates.isOpenApi3_1Element(parentOpenapiElement)) {
+          const openapiServersContent = parentOpenapiElement.servers?.content;
+          const openapiServers = openapiServersContent ?? [];
+          if (isServersUndefined || !isServersArrayElement) {
+            pathItemElement.servers = new PathItemServersElement(openapiServers);
+          } else if (isServersArrayElement && isServersEmpty) {
+            openapiServers.forEach(server => {
+              pathItemElement.servers.push(server);
+            });
+          }
+          storage.append(pathItemJSONPointer);
+        }
+      },
+      OperationElement(operationElement, key, parent, path, ancestors) {
+        // skip visiting this Operation
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+        const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, operationElement]);
+
+        // skip visiting this Operation Object if it's already normalized
+        if (storage.includes(operationJSONPointer)) {
+          return;
+        }
+
+        // @TODO(vladimir.gorej@gmail.com): can be replaced by Array.prototype.findLast in future
+        const parentPathItemElement = [...ancestors].reverse().find(predicates.isPathItemElement);
+        const isServersUndefined = typeof operationElement.servers === 'undefined';
+        const isServersArrayElement = predicates.isArrayElement(operationElement.servers);
+        const isServersEmpty = isServersArrayElement && operationElement.servers.length === 0;
+        if (predicates.isPathItemElement(parentPathItemElement)) {
+          const pathItemServersContent = parentPathItemElement.servers?.content;
+          const pathItemServers = pathItemServersContent ?? [];
+          if (isServersUndefined || !isServersArrayElement) {
+            // duplicate parent PathItem.servers into this Operation object
+            operationElement.servers = new OperationServersElement(pathItemServers);
+          } else if (isServersArrayElement && isServersEmpty) {
+            pathItemServers.forEach(server => {
+              operationElement.servers.push(server);
+            });
+          }
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+export default plugin;