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

package/src/refractor/plugins/normalize-header-examples/index.mjs

@@ -0,0 +1,99 @@
+import { cloneDeep } from '@speclynx/apidom-core';
+import NormalizeStorage from "./NormalizeStorage.mjs";
+/**
+ * Override of Schema.example and Schema.examples field inside the Header Objects.
+ *
+ * Header 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(element) {
+          storage = new NormalizeStorage(element, storageField, 'header-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      HeaderElement: {
+        leave(headerElement, key, parent, path, ancestors) {
+          // skip visiting this Header Object
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+
+          // no Header.schema field present
+          if (typeof headerElement.schema === 'undefined' || !predicates.isSchemaElement(headerElement.schema)) {
+            return;
+          }
+          // Schema contains no example
+          if (typeof headerElement.schema?.example === 'undefined' && typeof headerElement.schema?.examples === 'undefined') {
+            return;
+          }
+          const headerJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, headerElement]);
+
+          // skip visiting this Header Object if it's already normalized
+          if (storage.includes(headerJSONPointer)) {
+            return;
+          }
+
+          /**
+           * Header.examples and Schema.examples have preferences over the older
+           * and deprected `example` field.
+           */
+          if (typeof headerElement.examples !== 'undefined' && predicates.isObjectElement(headerElement.examples)) {
+            // @ts-ignore
+            const examples = headerElement.examples.map(example => {
+              return cloneDeep.safe(example.value);
+            });
+            if (typeof headerElement.schema.examples !== 'undefined') {
+              headerElement.schema.set('examples', examples);
+              storage.append(headerJSONPointer);
+            }
+            if (typeof headerElement.schema.example !== 'undefined') {
+              headerElement.schema.set('example', examples[0]);
+              storage.append(headerJSONPointer);
+            }
+            return;
+          }
+
+          /**
+           * Handle deprecated `example` field.
+           */
+          if (typeof headerElement.example !== 'undefined') {
+            if (typeof headerElement.schema.examples !== 'undefined') {
+              headerElement.schema.set('examples', [cloneDeep(headerElement.example)]);
+              storage.append(headerJSONPointer);
+            }
+            if (typeof headerElement.schema.example !== 'undefined') {
+              headerElement.schema.set('example', cloneDeep(headerElement.example));
+              storage.append(headerJSONPointer);
+            }
+          }
+        }
+      }
+    }
+  };
+};
+export default plugin;

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

@@ -0,0 +1,159 @@
+"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 _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(element) {
+          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 = (0, _apidomCore.toValue)(normalizedOperationElement.meta.get('originalOperationId'));
+              return originalOperationId === linkOperationId;
+            });
+
+            // Link Object doesn't need to be rectified
+            if (typeof operationElement === 'undefined') return;
+            linkElement.operationId = _apidomCore.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(pathItemElement) {
+          // `path` meta may not be always available, e.g. in Callback Object or Components Object
+          const pathTemplate = (0, _ramda.defaultTo)('path', (0, _apidomCore.toValue)(pathItemElement.meta.get('path')));
+          pathTemplates.push(pathTemplate);
+        },
+        leave() {
+          pathTemplates.pop();
+        }
+      },
+      OperationElement: {
+        enter(operationElement, key, parent, path, ancestors) {
+          // operationId field is undefined, needs no normalization
+          if (typeof operationElement.operationId === 'undefined') return;
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, 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', (0, _apidomCore.toValue)(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(linkElement) {
+          // 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,154 @@
+import { last, defaultTo, groupBy } from 'ramda';
+import { toValue, cloneDeep } 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(element) {
+          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 = toValue(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(pathItemElement) {
+          // `path` meta may not be always available, e.g. in Callback Object or Components Object
+          const pathTemplate = defaultTo('path', toValue(pathItemElement.meta.get('path')));
+          pathTemplates.push(pathTemplate);
+        },
+        leave() {
+          pathTemplates.pop();
+        }
+      },
+      OperationElement: {
+        enter(operationElement, key, parent, path, ancestors) {
+          // operationId field is undefined, needs no normalization
+          if (typeof operationElement.operationId === 'undefined') return;
+          const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, 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', toValue(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(linkElement) {
+          // 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,105 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+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(element) {
+          storage = new _NormalizeStorage.default(element, storageField, 'parameter-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      ParameterElement: {
+        leave(parameterElement, key, parent, path, ancestors) {
+          // 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, parent, 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 _apidomCore.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, _apidomCore.cloneDeep)(parameterElement.example)]);
+              storage.append(parameterJSONPointer);
+            }
+            if (typeof parameterElement.schema.example !== 'undefined') {
+              parameterElement.schema.set('example', (0, _apidomCore.cloneDeep)(parameterElement.example));
+              storage.append(parameterJSONPointer);
+            }
+          }
+        }
+      }
+    }
+  };
+};
+var _default = exports.default = plugin;

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

@@ -0,0 +1,99 @@
+import { cloneDeep } from '@speclynx/apidom-core';
+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(element) {
+          storage = new NormalizeStorage(element, storageField, 'parameter-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      ParameterElement: {
+        leave(parameterElement, key, parent, path, ancestors) {
+          // 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, parent, 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;