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

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

@@ -0,0 +1,118 @@
+import { PathItemServersElement, OperationServersElement, ServersElement } from '@speclynx/apidom-ns-openapi-3-0';
+import NormalizeStorage from "./normalize-header-examples/NormalizeStorage.mjs";
+import { refractServer } from "../index.mjs";
+/**
+ * Override of Server Objects.
+ *
+ * List of Server Objects can be defined in OpenAPI 3.1 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
+ */
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    ancestorLineageToJSONPointer,
+    predicates
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(path) {
+          const openapiElement = path.node;
+          const isServersUndefined = typeof openapiElement.servers === 'undefined';
+          const isServersArrayElement = predicates.isArrayElement(openapiElement.servers);
+          const isServersEmpty = isServersArrayElement && openapiElement.servers.length === 0;
+          const defaultServer = refractServer({
+            url: '/'
+          });
+          if (isServersUndefined || !isServersArrayElement) {
+            openapiElement.servers = new ServersElement([defaultServer]);
+          } else if (isServersArrayElement && isServersEmpty) {
+            openapiElement.servers.push(defaultServer);
+          }
+          storage = new NormalizeStorage(openapiElement, storageField, 'servers');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      PathItemElement(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;
+        if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+        const pathItemJSONPointer = ancestorLineageToJSONPointer([...ancestors, pathItemElement]);
+
+        // skip visiting this Path Item Object if it's already normalized
+        if (storage.includes(pathItemJSONPointer)) {
+          return;
+        }
+        const parentOpenapiElement = ancestors.find(predicates.isOpenApi3_1Element);
+        const isServersUndefined = typeof pathItemElement.servers === 'undefined';
+        const isServersArrayElement = predicates.isArrayElement(pathItemElement.servers);
+        const isServersEmpty = isServersArrayElement && pathItemElement.servers.length === 0;
+
+        // duplicate OpenAPI.servers into this Path Item object
+        if (predicates.isOpenApi3_1Element(parentOpenapiElement)) {
+          const openapiServersContent = parentOpenapiElement.servers?.content;
+          const openapiServers = openapiServersContent ?? [];
+          if (isServersUndefined || !isServersArrayElement) {
+            pathItemElement.servers = new PathItemServersElement(openapiServers);
+          } else if (isServersArrayElement && isServersEmpty) {
+            openapiServers.forEach(server => {
+              pathItemElement.servers.push(server);
+            });
+          }
+          storage.append(pathItemJSONPointer);
+        }
+      },
+      OperationElement(path) {
+        const operationElement = path.node;
+        const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+        // skip visiting this Operation
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+        const operationJSONPointer = ancestorLineageToJSONPointer([...ancestors, operationElement]);
+
+        // skip visiting this Operation Object if it's already normalized
+        if (storage.includes(operationJSONPointer)) {
+          return;
+        }
+
+        // @TODO(vladimir.gorej@gmail.com): can be replaced by Array.prototype.findLast in future
+        const parentPathItemElement = ancestors.findLast(predicates.isPathItemElement);
+        const isServersUndefined = typeof operationElement.servers === 'undefined';
+        const isServersArrayElement = predicates.isArrayElement(operationElement.servers);
+        const isServersEmpty = isServersArrayElement && operationElement.servers.length === 0;
+        if (predicates.isPathItemElement(parentPathItemElement)) {
+          const pathItemServersContent = parentPathItemElement.servers?.content;
+          const pathItemServers = pathItemServersContent ?? [];
+          if (isServersUndefined || !isServersArrayElement) {
+            // duplicate parent PathItem.servers into this Operation object
+            operationElement.servers = new OperationServersElement(pathItemServers);
+          } else if (isServersArrayElement && isServersEmpty) {
+            pathItemServers.forEach(server => {
+              operationElement.servers.push(server);
+            });
+          }
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+export default plugin;

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

@@ -0,0 +1,144 @@
+import { Path } from '@speclynx/apidom-traverse';
+import {
+  PathItemServersElement,
+  OperationServersElement,
+  ServersElement,
+} from '@speclynx/apidom-ns-openapi-3-0';
+
+import type OpenApi3_1Element from '../../elements/OpenApi3-1.ts';
+import type PathItemElement from '../../elements/PathItem.ts';
+import type ServerElement from '../../elements/Server.ts';
+import type OperationElement from '../../elements/Operation.ts';
+import type { Toolbox } from '../toolbox.ts';
+import NormalizeStorage from './normalize-header-examples/NormalizeStorage.ts';
+import { refractServer } from '../index.ts';
+
+/**
+ * Override of Server Objects.
+ *
+ * List of Server Objects can be defined in OpenAPI 3.1 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 interface PluginOptions {
+  storageField?: string;
+}
+
+/**
+ * @public
+ */
+const plugin =
+  ({ storageField = 'x-normalized' }: PluginOptions = {}) =>
+  (toolbox: Toolbox) => {
+    const { ancestorLineageToJSONPointer, predicates } = toolbox;
+    let storage: NormalizeStorage | undefined;
+
+    return {
+      visitor: {
+        OpenApi3_1Element: {
+          enter(path: Path<OpenApi3_1Element>) {
+            const openapiElement = path.node;
+            const isServersUndefined = typeof openapiElement.servers === 'undefined';
+            const isServersArrayElement = predicates.isArrayElement(openapiElement.servers);
+            const isServersEmpty = isServersArrayElement && openapiElement.servers!.length === 0;
+            const defaultServer = refractServer({ url: '/' });
+
+            if (isServersUndefined || !isServersArrayElement) {
+              openapiElement.servers = new ServersElement([defaultServer]);
+            } else if (isServersArrayElement && isServersEmpty) {
+              openapiElement.servers!.push(defaultServer);
+            }
+            storage = new NormalizeStorage(openapiElement, storageField, 'servers');
+          },
+          leave() {
+            storage = undefined;
+          },
+        },
+        PathItemElement(path: Path<PathItemElement>) {
+          const pathItemElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // skip visiting this Path Item
+          if (ancestors.some(predicates.isComponentsElement)) return;
+          if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+
+          const pathItemJSONPointer = ancestorLineageToJSONPointer([...ancestors, pathItemElement]);
+
+          // skip visiting this Path Item Object if it's already normalized
+          if (storage!.includes(pathItemJSONPointer)) {
+            return;
+          }
+
+          const parentOpenapiElement = ancestors.find(predicates.isOpenApi3_1Element);
+          const isServersUndefined = typeof pathItemElement.servers === 'undefined';
+          const isServersArrayElement = predicates.isArrayElement(pathItemElement.servers);
+          const isServersEmpty = isServersArrayElement && pathItemElement.servers!.length === 0;
+
+          // duplicate OpenAPI.servers into this Path Item object
+          if (predicates.isOpenApi3_1Element(parentOpenapiElement)) {
+            const openapiServersContent = (parentOpenapiElement as unknown as OpenApi3_1Element)
+              .servers?.content;
+            const openapiServers = (openapiServersContent ?? []) as ServerElement[];
+
+            if (isServersUndefined || !isServersArrayElement) {
+              pathItemElement.servers = new PathItemServersElement(openapiServers);
+            } else if (isServersArrayElement && isServersEmpty) {
+              openapiServers.forEach((server) => {
+                pathItemElement.servers!.push(server);
+              });
+            }
+            storage!.append(pathItemJSONPointer);
+          }
+        },
+        OperationElement(path: Path<OperationElement>) {
+          const operationElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // skip visiting this Operation
+          if (ancestors.some(predicates.isComponentsElement)) return;
+          if (!ancestors.some(predicates.isOpenApi3_1Element)) return;
+
+          const operationJSONPointer = ancestorLineageToJSONPointer([
+            ...ancestors,
+            operationElement,
+          ]);
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage!.includes(operationJSONPointer)) {
+            return;
+          }
+
+          // @TODO(vladimir.gorej@gmail.com): can be replaced by Array.prototype.findLast in future
+          const parentPathItemElement = ancestors.findLast(predicates.isPathItemElement);
+          const isServersUndefined = typeof operationElement.servers === 'undefined';
+          const isServersArrayElement = predicates.isArrayElement(operationElement.servers);
+          const isServersEmpty = isServersArrayElement && operationElement.servers!.length === 0;
+
+          if (predicates.isPathItemElement(parentPathItemElement)) {
+            const pathItemServersContent = (parentPathItemElement as unknown as PathItemElement)
+              .servers?.content;
+            const pathItemServers = (pathItemServersContent ?? []) as ServerElement[];
+
+            if (isServersUndefined || !isServersArrayElement) {
+              // duplicate parent PathItem.servers into this Operation object
+              operationElement.servers = new OperationServersElement(pathItemServers);
+            } else if (isServersArrayElement && isServersEmpty) {
+              pathItemServers.forEach((server) => {
+                operationElement.servers!.push(server);
+              });
+            }
+            storage!.append(operationJSONPointer);
+          }
+        },
+      },
+    };
+  };
+
+export default plugin;