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

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

@@ -0,0 +1,198 @@
+import { last, defaultTo, groupBy } from 'ramda';
+import { StringElement, cloneDeep } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import { Path } from '@speclynx/apidom-traverse';
+
+import LinkElement from '../../elements/Link.ts';
+import PathItemElement from '../../elements/PathItem.ts';
+import OperationElement from '../../elements/Operation.ts';
+import type { Toolbox } from '../toolbox.ts';
+import OpenApi3_1Element from '../../elements/OpenApi3-1.ts';
+import NormalizeStorage from './normalize-header-examples/NormalizeStorage.ts';
+
+const removeSpaces = (operationId: string) => {
+  return operationId.replace(/\s/g, '');
+};
+
+const replaceSpecialCharsWithUnderscore = (operationId: string) => {
+  return operationId.replace(/\W/gi, '_');
+};
+
+const createNormalizedOperationId = (path: string, method: string) => {
+  const normalizedMethod = replaceSpecialCharsWithUnderscore(removeSpaces(method.toLowerCase()));
+  const normalizedPath = replaceSpecialCharsWithUnderscore(removeSpaces(path));
+
+  return `${normalizedMethod}${normalizedPath}`;
+};
+
+const normalizeOperationId = (operationId: string, path: string, method: string) => {
+  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
+ */
+
+export interface PluginOptions {
+  storageField?: string;
+  operationIdNormalizer?: (operationId: string, path: string, method: string) => string;
+}
+
+/**
+ * @public
+ */
+const plugin =
+  ({
+    storageField = 'x-normalized',
+    operationIdNormalizer = normalizeOperationId,
+  }: PluginOptions = {}) =>
+  (toolbox: Toolbox) => {
+    const { predicates, ancestorLineageToJSONPointer, namespace } = toolbox;
+    const pathTemplates: string[] = [];
+    const normalizedOperations: OperationElement[] = [];
+    const links: LinkElement[] = [];
+    let storage: NormalizeStorage | undefined;
+
+    return {
+      visitor: {
+        OpenApi3_1Element: {
+          enter(path: Path<OpenApi3_1Element>) {
+            const element = path.node;
+            storage = new NormalizeStorage(element, storageField, 'operation-ids');
+          },
+          leave() {
+            // group normalized operations by normalized operationId
+            const normalizedOperationGroups = groupBy((operationElement: OperationElement) => {
+              return toValue(operationElement.operationId as StringElement) as string;
+            }, 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: Path<PathItemElement>) {
+            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') as string);
+            pathTemplates.push(pathTemplate);
+          },
+          leave() {
+            pathTemplates.pop();
+          },
+        },
+        OperationElement: {
+          enter(path: Path<OperationElement>) {
+            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) as string;
+            // `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')) as string;
+            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: Path<LinkElement>) {
+            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-parameter-examples.ts

@@ -0,0 +1,128 @@
+import { cloneDeep } from '@speclynx/apidom-datamodel';
+import { Path } from '@speclynx/apidom-traverse';
+
+import ParameterElement from '../../elements/Parameter.ts';
+import ExampleElement from '../../elements/Example.ts';
+import type { Toolbox } from '../toolbox.ts';
+import OpenApi3_1Element from '../../elements/OpenApi3-1.ts';
+import NormalizeStorage from './normalize-header-examples/NormalizeStorage.ts';
+
+/**
+ * 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
+ */
+
+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, 'parameter-examples');
+          },
+          leave() {
+            storage = undefined;
+          },
+        },
+        ParameterElement: {
+          leave(path: Path<ParameterElement>) {
+            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: ExampleElement) => {
+                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;