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

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

@@ -0,0 +1,103 @@
+import { cloneDeep } from '@speclynx/apidom-datamodel';
+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(path) {
+          const element = path.node;
+          storage = new NormalizeStorage(element, storageField, 'header-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      HeaderElement: {
+        leave(path) {
+          const headerElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // 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, 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-header-examples/index.ts

@@ -0,0 +1,125 @@
+import { cloneDeep } from '@speclynx/apidom-datamodel';
+import { Path } from '@speclynx/apidom-traverse';
+
+import HeaderElement from '../../../elements/Header.ts';
+import ExampleElement from '../../../elements/Example.ts';
+import type { Toolbox } from '../../toolbox.ts';
+import OpenApi3_1Element from '../../../elements/OpenApi3-1.ts';
+import NormalizeStorage from './NormalizeStorage.ts';
+
+/**
+ * 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
+ */
+
+export interface PluginOptions {
+  storageField?: string;
+}
+
+/**
+ * @public
+ */
+const plugin =
+  ({ storageField = 'x-normalized' }: PluginOptions = {}) =>
+  (toolbox: Toolbox) => {
+    const { predicates, ancestorLineageToJSONPointer } = toolbox;
+    let storage: NormalizeStorage | undefined;
+
+    return {
+      visitor: {
+        OpenApi3_1Element: {
+          enter(path: Path<OpenApi3_1Element>) {
+            const element = path.node;
+            storage = new NormalizeStorage(element, storageField, 'header-examples');
+          },
+          leave() {
+            storage = undefined;
+          },
+        },
+        HeaderElement: {
+          leave(path: Path<HeaderElement>) {
+            const headerElement = path.node;
+            const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+            // 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, 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: ExampleElement) => {
+                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,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;