@speclynx/apidom-ns-openapi-3-1 4.0.2 → 4.0.4

package/src/refractor/plugins/normalize-operation-ids.cjs

@@ -0,0 +1,166 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _NormalizeStorage = _interopRequireDefault(require("./normalize-header-examples/NormalizeStorage.cjs"));
+const removeSpaces = operationId => {
+  return operationId.replace(/\s/g, '');
+};
+const replaceSpecialCharsWithUnderscore = operationId => {
+  return operationId.replace(/\W/gi, '_');
+};
+const createNormalizedOperationId = (path, method) => {
+  const normalizedMethod = replaceSpecialCharsWithUnderscore(removeSpaces(method.toLowerCase()));
+  const normalizedPath = replaceSpecialCharsWithUnderscore(removeSpaces(path));
+  return `${normalizedMethod}${normalizedPath}`;
+};
+const normalizeOperationId = (operationId, path, method) => {
+  const withoutSpaces = removeSpaces(operationId);
+  if (withoutSpaces.length > 0) {
+    return replaceSpecialCharsWithUnderscore(withoutSpaces);
+  }
+  return createNormalizedOperationId(path, method);
+};
+
+/**
+ * Normalization of Operation.operationId field.
+ *
+ * This normalization is not guided by OpenAPI 3.1 specification.
+ *
+ * Existing Operation.operationId fields are normalized into snake case form.
+ *
+ * Operation Objects, that do not define operationId field, are left untouched.
+ *
+ * Original operationId is stored in meta and as new `__originalOperationId` field.
+ *
+ * This plugin also guarantees the uniqueness of all defined Operation.operationId fields,
+ * and make sure Link.operationId fields are pointing to correct and normalized Operation.operationId fields.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized',
+  operationIdNormalizer = normalizeOperationId
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer,
+    namespace
+  } = toolbox;
+  const pathTemplates = [];
+  const normalizedOperations = [];
+  const links = [];
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(path) {
+          const element = path.node;
+          storage = new _NormalizeStorage.default(element, storageField, 'operation-ids');
+        },
+        leave() {
+          // group normalized operations by normalized operationId
+          const normalizedOperationGroups = (0, _ramda.groupBy)(operationElement => {
+            return (0, _apidomCore.toValue)(operationElement.operationId);
+          }, normalizedOperations);
+
+          // append incremental numerical suffixes to identical operationIds
+          Object.entries(normalizedOperationGroups).forEach(([normalizedOperationId, operationElements]) => {
+            if (!Array.isArray(operationElements)) return;
+            if (operationElements.length <= 1) return;
+            operationElements.forEach((operationElement, index) => {
+              const indexedNormalizedOperationId = `${normalizedOperationId}${index + 1}`;
+              // @ts-ignore
+              operationElement.operationId = new namespace.elements.String(indexedNormalizedOperationId);
+            });
+          });
+
+          // rectify possibly broken Link.operationId fields
+          links.forEach(linkElement => {
+            if (typeof linkElement.operationId === 'undefined') return;
+            const linkOperationId = String((0, _apidomCore.toValue)(linkElement.operationId));
+            const operationElement = normalizedOperations.find(normalizedOperationElement => {
+              const originalOperationId = normalizedOperationElement.meta.get('originalOperationId');
+              return originalOperationId === linkOperationId;
+            });
+
+            // Link Object doesn't need to be rectified
+            if (typeof operationElement === 'undefined') return;
+            linkElement.operationId = _apidomDatamodel.cloneDeep.safe(operationElement.operationId);
+            linkElement.meta.set('originalOperationId', linkOperationId);
+            linkElement.set('__originalOperationId', linkOperationId);
+          });
+
+          // cleanup the references
+          normalizedOperations.length = 0;
+          links.length = 0;
+          storage = undefined;
+        }
+      },
+      PathItemElement: {
+        enter(path) {
+          const pathItemElement = path.node;
+          // `path` meta may not be always available, e.g. in Callback Object or Components Object
+          const pathTemplate = (0, _ramda.defaultTo)('path', pathItemElement.meta.get('path'));
+          pathTemplates.push(pathTemplate);
+        },
+        leave() {
+          pathTemplates.pop();
+        }
+      },
+      OperationElement: {
+        enter(path) {
+          const operationElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // operationId field is undefined, needs no normalization
+          if (typeof operationElement.operationId === 'undefined') return;
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+
+          // cast operationId to string type
+          const originalOperationId = String((0, _apidomCore.toValue)(operationElement.operationId));
+          // perform operationId normalization
+          const pathTemplate = (0, _ramda.last)(pathTemplates);
+          // `http-method` meta may not be always available, e.g. in Callback Object or Components Object
+          const method = (0, _ramda.defaultTo)('method', operationElement.meta.get('http-method'));
+          const normalizedOperationId = operationIdNormalizer(originalOperationId, pathTemplate, method);
+
+          // normalization is not necessary
+          if (originalOperationId === normalizedOperationId) return;
+
+          // @ts-ignore
+          operationElement.operationId = new namespace.elements.String(normalizedOperationId);
+          operationElement.set('__originalOperationId', originalOperationId);
+          operationElement.meta.set('originalOperationId', originalOperationId);
+          normalizedOperations.push(operationElement);
+          storage.append(operationJSONPointer);
+        }
+      },
+      LinkElement: {
+        leave(path) {
+          const linkElement = path.node;
+          // make sure this Link elements doesn't come from base namespace
+          if (!predicates.isLinkElement(linkElement)) return;
+          // ignore Link Objects with undefined operationId
+          if (typeof linkElement.operationId === 'undefined') return;
+          links.push(linkElement);
+        }
+      }
+    }
+  };
+};
+var _default = exports.default = plugin;

package/src/refractor/plugins/normalize-operation-ids.mjs

@@ -0,0 +1,161 @@
+import { last, defaultTo, groupBy } from 'ramda';
+import { cloneDeep } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
+const removeSpaces = operationId => {
+  return operationId.replace(/\s/g, '');
+};
+const replaceSpecialCharsWithUnderscore = operationId => {
+  return operationId.replace(/\W/gi, '_');
+};
+const createNormalizedOperationId = (path, method) => {
+  const normalizedMethod = replaceSpecialCharsWithUnderscore(removeSpaces(method.toLowerCase()));
+  const normalizedPath = replaceSpecialCharsWithUnderscore(removeSpaces(path));
+  return `${normalizedMethod}${normalizedPath}`;
+};
+const normalizeOperationId = (operationId, path, method) => {
+  const withoutSpaces = removeSpaces(operationId);
+  if (withoutSpaces.length > 0) {
+    return replaceSpecialCharsWithUnderscore(withoutSpaces);
+  }
+  return createNormalizedOperationId(path, method);
+};
+
+/**
+ * Normalization of Operation.operationId field.
+ *
+ * This normalization is not guided by OpenAPI 3.1 specification.
+ *
+ * Existing Operation.operationId fields are normalized into snake case form.
+ *
+ * Operation Objects, that do not define operationId field, are left untouched.
+ *
+ * Original operationId is stored in meta and as new `__originalOperationId` field.
+ *
+ * This plugin also guarantees the uniqueness of all defined Operation.operationId fields,
+ * and make sure Link.operationId fields are pointing to correct and normalized Operation.operationId fields.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized',
+  operationIdNormalizer = normalizeOperationId
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer,
+    namespace
+  } = toolbox;
+  const pathTemplates = [];
+  const normalizedOperations = [];
+  const links = [];
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(path) {
+          const element = path.node;
+          storage = new NormalizeStorage(element, storageField, 'operation-ids');
+        },
+        leave() {
+          // group normalized operations by normalized operationId
+          const normalizedOperationGroups = groupBy(operationElement => {
+            return toValue(operationElement.operationId);
+          }, normalizedOperations);
+
+          // append incremental numerical suffixes to identical operationIds
+          Object.entries(normalizedOperationGroups).forEach(([normalizedOperationId, operationElements]) => {
+            if (!Array.isArray(operationElements)) return;
+            if (operationElements.length <= 1) return;
+            operationElements.forEach((operationElement, index) => {
+              const indexedNormalizedOperationId = `${normalizedOperationId}${index + 1}`;
+              // @ts-ignore
+              operationElement.operationId = new namespace.elements.String(indexedNormalizedOperationId);
+            });
+          });
+
+          // rectify possibly broken Link.operationId fields
+          links.forEach(linkElement => {
+            if (typeof linkElement.operationId === 'undefined') return;
+            const linkOperationId = String(toValue(linkElement.operationId));
+            const operationElement = normalizedOperations.find(normalizedOperationElement => {
+              const originalOperationId = normalizedOperationElement.meta.get('originalOperationId');
+              return originalOperationId === linkOperationId;
+            });
+
+            // Link Object doesn't need to be rectified
+            if (typeof operationElement === 'undefined') return;
+            linkElement.operationId = cloneDeep.safe(operationElement.operationId);
+            linkElement.meta.set('originalOperationId', linkOperationId);
+            linkElement.set('__originalOperationId', linkOperationId);
+          });
+
+          // cleanup the references
+          normalizedOperations.length = 0;
+          links.length = 0;
+          storage = undefined;
+        }
+      },
+      PathItemElement: {
+        enter(path) {
+          const pathItemElement = path.node;
+          // `path` meta may not be always available, e.g. in Callback Object or Components Object
+          const pathTemplate = defaultTo('path', pathItemElement.meta.get('path'));
+          pathTemplates.push(pathTemplate);
+        },
+        leave() {
+          pathTemplates.pop();
+        }
+      },
+      OperationElement: {
+        enter(path) {
+          const operationElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // operationId field is undefined, needs no normalization
+          if (typeof operationElement.operationId === 'undefined') return;
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, operationElement]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+
+          // cast operationId to string type
+          const originalOperationId = String(toValue(operationElement.operationId));
+          // perform operationId normalization
+          const pathTemplate = last(pathTemplates);
+          // `http-method` meta may not be always available, e.g. in Callback Object or Components Object
+          const method = defaultTo('method', operationElement.meta.get('http-method'));
+          const normalizedOperationId = operationIdNormalizer(originalOperationId, pathTemplate, method);
+
+          // normalization is not necessary
+          if (originalOperationId === normalizedOperationId) return;
+
+          // @ts-ignore
+          operationElement.operationId = new namespace.elements.String(normalizedOperationId);
+          operationElement.set('__originalOperationId', originalOperationId);
+          operationElement.meta.set('originalOperationId', originalOperationId);
+          normalizedOperations.push(operationElement);
+          storage.append(operationJSONPointer);
+        }
+      },
+      LinkElement: {
+        leave(path) {
+          const linkElement = path.node;
+          // make sure this Link elements doesn't come from base namespace
+          if (!predicates.isLinkElement(linkElement)) return;
+          // ignore Link Objects with undefined operationId
+          if (typeof linkElement.operationId === 'undefined') return;
+          links.push(linkElement);
+        }
+      }
+    }
+  };
+};
+export default plugin;

package/src/refractor/plugins/normalize-parameter-examples.cjs

@@ -0,0 +1,109 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _NormalizeStorage = _interopRequireDefault(require("./normalize-header-examples/NormalizeStorage.cjs"));
+/**
+ * Override of Schema.example and Schema.examples field inside the Parameter Objects.
+ *
+ * Parameter Object has two fixed fields:
+ *  - `example` of type `Any`
+ *  - `examples` of type `Map[string, Example Object | Reference Object]`
+ *
+ * OpenAPI 3.1 specification excerpt that defines the override behavior:
+ *
+ * The example value SHALL override the example provided by the schema.
+ * Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(path) {
+          const element = path.node;
+          storage = new _NormalizeStorage.default(element, storageField, 'parameter-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      ParameterElement: {
+        leave(path) {
+          const parameterElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // skip visiting this Parameter Object
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+
+          // no Parameter.schema field present
+          if (typeof parameterElement.schema === 'undefined' || !predicates.isSchemaElement(parameterElement.schema)) {
+            return;
+          }
+          // Schema contains no example
+          if (typeof parameterElement.schema?.example === 'undefined' && typeof parameterElement.schema?.examples === 'undefined') {
+            return;
+          }
+          const parameterJSONPointer = ancestorLineageToJSONPointer([...ancestors, parameterElement]);
+
+          // skip visiting this Parameter Object if it's already normalized
+          if (storage.includes(parameterJSONPointer)) {
+            return;
+          }
+
+          /**
+           * Parameter.examples and Schema.examples have preferences over the older
+           * and deprected `example` field.
+           */
+          if (typeof parameterElement.examples !== 'undefined' && predicates.isObjectElement(parameterElement.examples)) {
+            // @ts-ignore
+            const examples = parameterElement.examples.map(example => {
+              return _apidomDatamodel.cloneDeep.safe(example.value);
+            });
+            if (typeof parameterElement.schema.examples !== 'undefined') {
+              parameterElement.schema.set('examples', examples);
+              storage.append(parameterJSONPointer);
+            }
+            if (typeof parameterElement.schema.example !== 'undefined') {
+              parameterElement.schema.set('example', examples[0]);
+              storage.append(parameterJSONPointer);
+            }
+            return;
+          }
+
+          /**
+           * Handle deprecated `example` field.
+           */
+          if (typeof parameterElement.example !== 'undefined') {
+            if (typeof parameterElement.schema.examples !== 'undefined') {
+              parameterElement.schema.set('examples', [(0, _apidomDatamodel.cloneDeep)(parameterElement.example)]);
+              storage.append(parameterJSONPointer);
+            }
+            if (typeof parameterElement.schema.example !== 'undefined') {
+              parameterElement.schema.set('example', (0, _apidomDatamodel.cloneDeep)(parameterElement.example));
+              storage.append(parameterJSONPointer);
+            }
+          }
+        }
+      }
+    }
+  };
+};
+var _default = exports.default = plugin;

package/src/refractor/plugins/normalize-parameter-examples.mjs

@@ -0,0 +1,103 @@
+import { cloneDeep } from '@speclynx/apidom-datamodel';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
+/**
+ * Override of Schema.example and Schema.examples field inside the Parameter Objects.
+ *
+ * Parameter Object has two fixed fields:
+ *  - `example` of type `Any`
+ *  - `examples` of type `Map[string, Example Object | Reference Object]`
+ *
+ * OpenAPI 3.1 specification excerpt that defines the override behavior:
+ *
+ * The example value SHALL override the example provided by the schema.
+ * Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(path) {
+          const element = path.node;
+          storage = new NormalizeStorage(element, storageField, 'parameter-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      ParameterElement: {
+        leave(path) {
+          const parameterElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // skip visiting this Parameter Object
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+
+          // no Parameter.schema field present
+          if (typeof parameterElement.schema === 'undefined' || !predicates.isSchemaElement(parameterElement.schema)) {
+            return;
+          }
+          // Schema contains no example
+          if (typeof parameterElement.schema?.example === 'undefined' && typeof parameterElement.schema?.examples === 'undefined') {
+            return;
+          }
+          const parameterJSONPointer = ancestorLineageToJSONPointer([...ancestors, parameterElement]);
+
+          // skip visiting this Parameter Object if it's already normalized
+          if (storage.includes(parameterJSONPointer)) {
+            return;
+          }
+
+          /**
+           * Parameter.examples and Schema.examples have preferences over the older
+           * and deprected `example` field.
+           */
+          if (typeof parameterElement.examples !== 'undefined' && predicates.isObjectElement(parameterElement.examples)) {
+            // @ts-ignore
+            const examples = parameterElement.examples.map(example => {
+              return cloneDeep.safe(example.value);
+            });
+            if (typeof parameterElement.schema.examples !== 'undefined') {
+              parameterElement.schema.set('examples', examples);
+              storage.append(parameterJSONPointer);
+            }
+            if (typeof parameterElement.schema.example !== 'undefined') {
+              parameterElement.schema.set('example', examples[0]);
+              storage.append(parameterJSONPointer);
+            }
+            return;
+          }
+
+          /**
+           * Handle deprecated `example` field.
+           */
+          if (typeof parameterElement.example !== 'undefined') {
+            if (typeof parameterElement.schema.examples !== 'undefined') {
+              parameterElement.schema.set('examples', [cloneDeep(parameterElement.example)]);
+              storage.append(parameterJSONPointer);
+            }
+            if (typeof parameterElement.schema.example !== 'undefined') {
+              parameterElement.schema.set('example', cloneDeep(parameterElement.example));
+              storage.append(parameterJSONPointer);
+            }
+          }
+        }
+      }
+    }
+  };
+};
+export default plugin;

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

@@ -0,0 +1,109 @@
+"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(path) {
+          const element = path.node;
+          storage = new _NormalizeStorage.default(element, storageField, 'parameters');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      PathItemElement: {
+        enter(path) {
+          const pathItemElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // 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(path) {
+          const operationElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+          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, 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;