@speclynx/apidom-ns-openapi-3-0 4.1.0 → 4.3.0

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

@@ -0,0 +1,143 @@
+import { isArrayElement } from '@speclynx/apidom-datamodel';
+import ServersElement from "../../elements/nces/Servers.mjs";
+import PathItemServersElement from "../../elements/nces/PathItemServers.mjs";
+import OperationServersElement from "../../elements/nces/OperationServers.mjs";
+import NormalizeStorage from "./normalize-storage/index.mjs";
+import { refractServer } from "../index.mjs";
+/**
+ * Override of Server Objects.
+ *
+ * List of Server Objects can be defined in OpenAPI 3.0 on multiple levels:
+ *
+ *  - OpenAPI.servers
+ *  - PathItem.servers
+ *  - Operation.servers
+ *
+ * If a servers array is specified at the OpenAPI Object level, it will be overridden by `PathItem`.servers.
+ * If a servers array is specified at the Path Item Object or OpenAPI Object level, it will be overridden by Operation.servers.
+ * @public
+ */
+/**
+ * Ensures the OpenAPI document has at least one server defined.
+ * If `servers` is missing or empty, adds a default server with `url: "/"`.
+ * @public
+ */
+const ensureDefaultServer = openapiElement => {
+  const isServersUndefined = typeof openapiElement.servers === 'undefined';
+  const isServersArray = isArrayElement(openapiElement.servers);
+  const isServersEmpty = isServersArray && openapiElement.servers.length === 0;
+  const defaultServer = refractServer({
+    url: '/'
+  });
+  if (isServersUndefined || !isServersArray) {
+    openapiElement.servers = new ServersElement([defaultServer]);
+  } else if (isServersArray && isServersEmpty) {
+    openapiElement.servers.push(defaultServer);
+  }
+};
+
+/**
+ * Inherits servers from the OpenAPI root into a PathItem element.
+ * If PathItem.servers is missing or empty, copies from OpenAPI.servers.
+ * @public
+ */
+const inheritServersToPathItem = (pathItemElement, openapiElement) => {
+  const isServersUndefined = typeof pathItemElement.servers === 'undefined';
+  const isServersArray = isArrayElement(pathItemElement.servers);
+  const isServersEmpty = isServersArray && pathItemElement.servers.length === 0;
+  const openapiServers = [...(openapiElement.servers ?? [])];
+  if (isServersUndefined || !isServersArray) {
+    pathItemElement.servers = new PathItemServersElement(openapiServers);
+  } else if (isServersArray && isServersEmpty) {
+    openapiServers.forEach(server => {
+      pathItemElement.servers.push(server);
+    });
+  }
+};
+
+/**
+ * Inherits servers from a PathItem into an Operation element.
+ * If Operation.servers is missing or empty, copies from PathItem.servers.
+ * @public
+ */
+const inheritServersToOperation = (operationElement, pathItemElement) => {
+  const isServersUndefined = typeof operationElement.servers === 'undefined';
+  const isServersArray = isArrayElement(operationElement.servers);
+  const isServersEmpty = isServersArray && operationElement.servers.length === 0;
+  const pathItemServers = [...(pathItemElement.servers ?? [])];
+  if (isServersUndefined || !isServersArray) {
+    operationElement.servers = new OperationServersElement(pathItemServers);
+  } else if (isServersArray && isServersEmpty) {
+    pathItemServers.forEach(server => {
+      operationElement.servers.push(server);
+    });
+  }
+};
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_0Element: {
+        enter(path) {
+          const openapiElement = path.node;
+          ensureDefaultServer(openapiElement);
+          storage = new NormalizeStorage(openapiElement, storageField, 'servers');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      PathItemElement(path) {
+        const pathItemElement = path.node;
+        const ancestors = path.getAncestorNodes(); // parent to root order
+
+        // skip visiting this Path Item
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_0Element)) return;
+        const pathItemJSONPointer = path.formatPath();
+
+        // skip visiting this Path Item Object if it's already normalized
+        if (storage.includes(pathItemJSONPointer)) {
+          return;
+        }
+        const parentOpenapiElement = ancestors.find(predicates.isOpenApi3_0Element);
+        if (predicates.isOpenApi3_0Element(parentOpenapiElement)) {
+          inheritServersToPathItem(pathItemElement, parentOpenapiElement);
+          storage.append(pathItemJSONPointer);
+        }
+      },
+      OperationElement(path) {
+        const operationElement = path.node;
+        const ancestors = path.getAncestorNodes(); // parent to root order
+
+        // skip visiting this Operation
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_0Element)) return;
+        const operationJSONPointer = path.formatPath();
+
+        // skip visiting this Operation Object if it's already normalized
+        if (storage.includes(operationJSONPointer)) {
+          return;
+        }
+        const parentPathItemElement = ancestors.find(predicates.isPathItemElement);
+        if (predicates.isPathItemElement(parentPathItemElement)) {
+          inheritServersToOperation(operationElement, parentPathItemElement);
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+plugin.ensureDefaultServer = ensureDefaultServer;
+plugin.inheritServersToPathItem = inheritServersToPathItem;
+plugin.inheritServersToOperation = inheritServersToOperation;
+export default plugin;

package/src/refractor/plugins/normalize-storage/index.cjs

@@ -0,0 +1,38 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+class NormalizeStorage {
+  internalStore;
+  constructor(storageElement, storageField, storageSubField) {
+    this.storageElement = storageElement;
+    this.storageField = storageField;
+    this.storageSubField = storageSubField;
+  }
+  get store() {
+    if (this.internalStore === undefined) {
+      let rootStore = this.storageElement.get(this.storageField);
+      if (!(0, _apidomDatamodel.isObjectElement)(rootStore)) {
+        rootStore = new _apidomDatamodel.ObjectElement();
+        this.storageElement.set(this.storageField, rootStore);
+      }
+      let store = rootStore.get(this.storageSubField);
+      if (!(0, _apidomDatamodel.isArrayElement)(store)) {
+        store = new _apidomDatamodel.ArrayElement();
+        rootStore.set(this.storageSubField, store);
+      }
+      this.internalStore = store;
+    }
+    return this.internalStore;
+  }
+  append(pointer) {
+    if (!this.includes(pointer)) {
+      this.store.push(pointer);
+    }
+  }
+  includes(pointer) {
+    return this.store.includes(pointer);
+  }
+}
+var _default = exports.default = NormalizeStorage;

package/src/refractor/plugins/normalize-storage/index.mjs

@@ -0,0 +1,34 @@
+import { ArrayElement, ObjectElement, isObjectElement, isArrayElement } from '@speclynx/apidom-datamodel';
+class NormalizeStorage {
+  internalStore;
+  constructor(storageElement, storageField, storageSubField) {
+    this.storageElement = storageElement;
+    this.storageField = storageField;
+    this.storageSubField = storageSubField;
+  }
+  get store() {
+    if (this.internalStore === undefined) {
+      let rootStore = this.storageElement.get(this.storageField);
+      if (!isObjectElement(rootStore)) {
+        rootStore = new ObjectElement();
+        this.storageElement.set(this.storageField, rootStore);
+      }
+      let store = rootStore.get(this.storageSubField);
+      if (!isArrayElement(store)) {
+        store = new ArrayElement();
+        rootStore.set(this.storageSubField, store);
+      }
+      this.internalStore = store;
+    }
+    return this.internalStore;
+  }
+  append(pointer) {
+    if (!this.includes(pointer)) {
+      this.store.push(pointer);
+    }
+  }
+  includes(pointer) {
+    return this.store.includes(pointer);
+  }
+}
+export default NormalizeStorage;

package/src/refractor/toolbox.cjs

@@ -12,12 +12,17 @@ var _namespace = _interopRequireDefault(require("../namespace.cjs"));
  * @public
  */
 
+/**
+ * @public
+ */
 const createToolbox = () => {
   const namespace = new _apidomDatamodel.Namespace();
   const predicates = {
     ...refractorPredicates,
     ...openApi3_0Predicates,
-    isStringElement: _apidomDatamodel.isStringElement
+    isStringElement: _apidomDatamodel.isStringElement,
+    isArrayElement: _apidomDatamodel.isArrayElement,
+    isObjectElement: _apidomDatamodel.isObjectElement
   };
   namespace.use(_namespace.default);
   return {

package/src/refractor/toolbox.mjs

@@ -1,7 +1,10 @@
-import { isStringElement, Namespace } from '@speclynx/apidom-datamodel';
+import { isStringElement, isArrayElement, isObjectElement, Namespace } from '@speclynx/apidom-datamodel';
 import * as openApi3_0Predicates from "../predicates.mjs";
 import * as refractorPredicates from "./predicates.mjs";
 import openApi3_0Namespace from "../namespace.mjs";
+/**
+ * @public
+ */
 /**
  * @public
  */
@@ -10,7 +13,9 @@ const createToolbox = () => {
   const predicates = {
     ...refractorPredicates,
     ...openApi3_0Predicates,
-    isStringElement
+    isStringElement,
+    isArrayElement,
+    isObjectElement
   };
   namespace.use(openApi3_0Namespace);
   return {

package/types/apidom-ns-openapi-3-0.d.ts

@@ -488,6 +488,11 @@ export declare class ContentVisitor extends BaseMapVisitor {
     constructor(options: BaseMapVisitorOptions);
 }
 
+/**
+ * @public
+ */
+export declare const createToolbox: () => Toolbox;
+
 /**
  * @public
  */
@@ -1815,6 +1820,111 @@ export declare type RefractorPlugin = (toolbox: Toolbox) => {
     post?: () => void;
 };
 
+/**
+ * @public
+ */
+export declare const refractorPluginNormalizeParameters: {
+    ({ storageField }?: RefractorPluginNormalizeParametersOptions): (toolbox: Toolbox) => {
+        visitor: {
+            OpenApi3_0Element: {
+                enter(path: Path<OpenApi3_0Element>): void;
+                leave(): void;
+            };
+            OperationElement: {
+                leave(path: Path<OperationElement>): void;
+            };
+        };
+    };
+    inheritParametersToOperation: (operationElement: OperationElement, pathItemElement: PathItemElement) => void;
+};
+
+/**
+ * Inheritance of Parameter Objects.
+ *
+ * OpenAPI 3.0 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
+ */
+export declare interface RefractorPluginNormalizeParametersOptions {
+    storageField?: string;
+}
+
+/**
+ * @public
+ */
+export declare const refractorPluginNormalizeSecurityRequirements: {
+    ({ storageField }?: RefractorPluginNormalizeSecurityRequirementsOptions): (toolbox: Toolbox) => {
+        visitor: {
+            OpenApi3_0Element: {
+                enter(path: Path<OpenApi3_0Element>): void;
+                leave(): void;
+            };
+            OperationElement: {
+                leave(path: Path<OperationElement>): void;
+            };
+        };
+    };
+    inheritSecurityToOperation: (operationElement: OperationElement, openapiElement: OpenApi3_0Element) => void;
+};
+
+/**
+ * Override of Security Requirement Objects.
+ *
+ * OpenAPI 3.0 specification excerpt that defines the override behavior:
+ *
+ * Operation.security definition overrides any declared top-level security.
+ * To remove a top-level security declaration, an empty array can be used.
+ * When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object,
+ * only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+export declare interface RefractorPluginNormalizeSecurityRequirementsOptions {
+    storageField?: string;
+}
+
+/**
+ * @public
+ */
+export declare const refractorPluginNormalizeServers: {
+    ({ storageField }?: RefractorPluginNormalizeServersOptions): (toolbox: Toolbox) => {
+        visitor: {
+            OpenApi3_0Element: {
+                enter(path: Path<OpenApi3_0Element>): void;
+                leave(): void;
+            };
+            PathItemElement(path: Path<PathItemElement>): void;
+            OperationElement(path: Path<OperationElement>): void;
+        };
+    };
+    ensureDefaultServer: (openapiElement: OpenApi3_0Element) => void;
+    inheritServersToPathItem: (pathItemElement: PathItemElement, openapiElement: OpenApi3_0Element) => void;
+    inheritServersToOperation: (operationElement: OperationElement, pathItemElement: PathItemElement) => void;
+};
+
+/**
+ * Override of Server Objects.
+ *
+ * List of Server Objects can be defined in OpenAPI 3.0 on multiple levels:
+ *
+ *  - OpenAPI.servers
+ *  - PathItem.servers
+ *  - Operation.servers
+ *
+ * If a servers array is specified at the OpenAPI Object level, it will be overridden by `PathItem`.servers.
+ * If a servers array is specified at the Path Item Object or OpenAPI Object level, it will be overridden by Operation.servers.
+ * @public
+ */
+export declare interface RefractorPluginNormalizeServersOptions {
+    storageField?: string;
+}
+
 /**
  * @public
  */