@scalar/postman-to-openapi 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/postman-to-openapi
 
+## 0.6.0
+
+### Minor Changes
+
+- [#8511](https://github.com/scalar/scalar/pull/8511): feat: support duplicate operations
+
+## 0.5.3
+
+### Patch Changes
+
+- [#8466](https://github.com/scalar/scalar/pull/8466): chore: new build pipeline
+
 ## 0.5.2
 
 ### Patch Changes

package/dist/convert.d.ts

@@ -1,9 +1,37 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
 import type { PostmanCollection } from './types.js';
+/**
+ * Indices from the collection root into nested `item` arrays.
+ * Example: `[0, 2, 1]` → `collection.item[0].item[2].item[1]`.
+ */
+export type PostmanRequestIndexPath = readonly number[];
+export type ConvertOptions = {
+    /**
+     * Whether to merge operations with the same path and method.
+     * If true, the operations will be merged into a single operation.
+     * If false, the operations will be kept as separate operations.
+     * Default is true.
+     */
+    mergeOperation?: boolean;
+    /**
+     * When set, only items at these paths are converted. Each path is a list of
+     * zero-based indices from `collection.item` through nested `item` arrays.
+     * The last index may point to a request or a folder; folders include every
+     * descendant request. Paths out of range or through non-folders are skipped.
+     * When omitted, the whole collection is converted (existing behavior).
+     */
+    requestIndexPaths?: readonly PostmanRequestIndexPath[];
+    /**
+     * Existing OpenAPI document to merge into. The input is is updated with Postman paths,
+     * tags (union by name), security schemes, and servers.
+     * Root `info` and existing paths are preserved unless Postman adds or merges operations.
+     */
+    document?: OpenAPIV3_1.Document;
+};
 /**
  * Converts a Postman Collection to an OpenAPI 3.1.0 document.
  * This function processes the collection's information, servers, authentication,
  * and items to create a corresponding OpenAPI structure.
  */
-export declare function convert(postmanCollection: PostmanCollection | string): OpenAPIV3_1.Document;
+export declare function convert(postmanCollection: PostmanCollection | string, options?: ConvertOptions): OpenAPIV3_1.Document;
 //# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAYxD,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAkL9E;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,iBAAiB,EAAE,iBAAiB,GAAG,MAAM,GAAG,WAAW,CAAC,QAAQ,CA6I3F"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAaxD,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAE9E;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,MAAM,EAAE,CAAA;AA4SvD,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAA;CAChC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,iBAAiB,EAAE,iBAAiB,GAAG,MAAM,EAC7C,OAAO,GAAE,cAA0C,GAClD,WAAW,CAAC,QAAQ,CAwLtB"}

package/dist/convert.js

@@ -1,233 +1,393 @@
-import { processAuth } from "./helpers/auth.js";
-import { processContact } from "./helpers/contact.js";
-import { processExternalDocs } from "./helpers/external-docs.js";
-import { processLicense } from "./helpers/license.js";
-import { processLogo } from "./helpers/logo.js";
-import { processItem } from "./helpers/path-items.js";
-import { pruneDocument } from "./helpers/prune-document.js";
-import { analyzeServerDistribution } from "./helpers/servers.js";
-import { normalizePath } from "./helpers/urls.js";
-const OPERATION_KEYS = [
-  "get",
-  "put",
-  "post",
-  "delete",
-  "options",
-  "head",
-  "patch",
-  "trace"
-];
+import { processAuth } from './helpers/auth.js';
+import { processContact } from './helpers/contact.js';
+import { processExternalDocs } from './helpers/external-docs.js';
+import { processLicense } from './helpers/license.js';
+import { processLogo } from './helpers/logo.js';
+import { DEFAULT_EXAMPLE_NAME, OPERATION_KEYS, mergePathItem } from './helpers/merge-path-item.js';
+import { processItem } from './helpers/path-items.js';
+import { pruneDocument } from './helpers/prune-document.js';
+import { analyzeServerDistribution } from './helpers/servers.js';
+import { normalizePath } from './helpers/urls.js';
 const normalizeDescription = (description) => {
-  if (typeof description === "string") {
-    return description;
-  }
-  return description?.content;
+    if (typeof description === 'string') {
+        return description;
+    }
+    return description?.content;
 };
 const parseCollectionInput = (postmanCollection) => {
-  if (typeof postmanCollection !== "string") {
-    return postmanCollection;
-  }
-  try {
-    return JSON.parse(postmanCollection);
-  } catch (error) {
-    const details = error instanceof Error ? error.message : "Unknown parse error";
-    const parseError = new Error(`Invalid Postman collection JSON: ${details}`);
-    parseError.name = "PostmanCollectionParseError";
-    throw parseError;
-  }
+    if (typeof postmanCollection !== 'string') {
+        return postmanCollection;
+    }
+    try {
+        return JSON.parse(postmanCollection);
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : 'Unknown parse error';
+        const parseError = new Error(`Invalid Postman collection JSON: ${details}`);
+        parseError.name = 'PostmanCollectionParseError';
+        throw parseError;
+    }
 };
 const validateCollectionShape = (collection) => {
-  if (!collection || typeof collection !== "object") {
-    throw new Error("Invalid Postman collection: expected an object");
-  }
-  const candidate = collection;
-  if (!candidate.info) {
-    throw new Error("Missing required info on Postman collection");
-  }
-  if (!candidate.item || !Array.isArray(candidate.item)) {
-    throw new Error("Invalid Postman collection: item must be an array");
-  }
-  if (typeof candidate.info !== "object") {
-    throw new Error("Invalid Postman collection: info must be an object");
-  }
-  if (!candidate.info.name) {
-    throw new Error("Missing required info.name on Postman collection");
-  }
-  if (!candidate.info.schema) {
-    throw new Error("Invalid Postman collection: missing info.schema");
-  }
-  if (candidate.variable && !Array.isArray(candidate.variable)) {
-    throw new Error("Invalid Postman collection: variable must be an array when provided");
-  }
-  return candidate;
+    if (!collection || typeof collection !== 'object') {
+        throw new Error('Invalid Postman collection: expected an object');
+    }
+    const candidate = collection;
+    if (!candidate.info) {
+        throw new Error('Missing required info on Postman collection');
+    }
+    if (!candidate.item || !Array.isArray(candidate.item)) {
+        throw new Error('Invalid Postman collection: item must be an array');
+    }
+    if (typeof candidate.info !== 'object') {
+        throw new Error('Invalid Postman collection: info must be an object');
+    }
+    if (!candidate.info.name) {
+        throw new Error('Missing required info.name on Postman collection');
+    }
+    if (!candidate.info.schema) {
+        throw new Error('Invalid Postman collection: missing info.schema');
+    }
+    if (candidate.variable && !Array.isArray(candidate.variable)) {
+        throw new Error('Invalid Postman collection: variable must be an array when provided');
+    }
+    return candidate;
 };
-const isItemGroup = (item) => "item" in item && Array.isArray(item.item);
+/**
+ * Extracts tags from Postman collection folders.
+ * We keep folder nesting using " > " so tag names stay readable while preserving hierarchy.
+ * Requests do not produce tags; only folders are reflected as tags.
+ */
+const isItemGroup = (item) => 'item' in item && Array.isArray(item.item);
 const extractTags = (items) => {
-  const collectTags = (item, parentPath = "") => {
-    if (!isItemGroup(item)) {
-      return [];
-    }
-    const nextPath = item.name ? parentPath ? `${parentPath} > ${item.name}` : item.name : parentPath;
-    const description = normalizeDescription(item.description);
-    const currentTag = item.name?.length ? [
-      {
-        name: nextPath,
-        ...description && { description }
-      }
-    ] : [];
-    return [...currentTag, ...item.item.flatMap((subItem) => collectTags(subItem, nextPath))];
-  };
-  return items.flatMap((item) => collectTags(item));
+    const collectTags = (item, parentPath = '') => {
+        if (!isItemGroup(item)) {
+            return [];
+        }
+        const nextPath = item.name ? (parentPath ? `${parentPath} > ${item.name}` : item.name) : parentPath;
+        const description = normalizeDescription(item.description);
+        const currentTag = item.name?.length
+            ? [
+                {
+                    name: nextPath,
+                    ...(description && { description }),
+                },
+            ]
+            : [];
+        return [...currentTag, ...item.item.flatMap((subItem) => collectTags(subItem, nextPath))];
+    };
+    return items.flatMap((item) => collectTags(item));
+};
+/**
+ * Folder tags for ancestors of each selected path only (same shape as {@link extractTags}).
+ */
+const extractTagsForSelectedPaths = (items, paths) => {
+    const seen = new Set();
+    const result = [];
+    for (const path of paths) {
+        if (path.length === 0) {
+            continue;
+        }
+        let list = items;
+        let parentPath = '';
+        for (let i = 0; i < path.length - 1; i++) {
+            const idx = path[i];
+            if (idx === undefined || idx < 0 || idx >= list.length) {
+                break;
+            }
+            const node = list[idx];
+            if (node === undefined || !isItemGroup(node)) {
+                break;
+            }
+            const nextPath = node.name ? (parentPath ? `${parentPath} > ${node.name}` : node.name) : parentPath;
+            const description = normalizeDescription(node.description);
+            if (node.name?.length && !seen.has(nextPath)) {
+                seen.add(nextPath);
+                result.push({
+                    name: nextPath,
+                    ...(description && { description }),
+                });
+            }
+            parentPath = nextPath;
+            list = node.item;
+        }
+    }
+    return result;
+};
+const getNodeAtPath = (items, path) => {
+    if (path.length === 0) {
+        return undefined;
+    }
+    let list = items;
+    let node;
+    for (let i = 0; i < path.length; i++) {
+        const idx = path[i];
+        if (idx === undefined || idx < 0 || idx >= list.length) {
+            return undefined;
+        }
+        node = list[idx];
+        if (node === undefined) {
+            return undefined;
+        }
+        if (i < path.length - 1) {
+            if (!isItemGroup(node)) {
+                return undefined;
+            }
+            list = node.item;
+        }
+    }
+    return node;
+};
+const collectParentTagSegments = (items, path) => {
+    const segments = [];
+    if (path.length <= 1) {
+        return segments;
+    }
+    let list = items;
+    for (let i = 0; i < path.length - 1; i++) {
+        const idx = path[i];
+        if (idx === undefined || idx < 0 || idx >= list.length) {
+            return [];
+        }
+        const node = list[idx];
+        if (node === undefined || !isItemGroup(node)) {
+            return [];
+        }
+        if (node.name) {
+            segments.push(node.name);
+        }
+        list = node.item;
+    }
+    return segments;
+};
+const dedupeIndexPaths = (paths) => {
+    const map = new Map();
+    for (const path of paths) {
+        map.set(JSON.stringify([...path]), path);
+    }
+    return [...map.values()];
 };
 const mergeSecuritySchemes = (openapi, securitySchemes) => {
-  if (!securitySchemes || Object.keys(securitySchemes).length === 0) {
-    return;
-  }
-  openapi.components = openapi.components || {};
-  openapi.components.securitySchemes = {
-    ...openapi.components.securitySchemes ?? {},
-    ...securitySchemes
-  };
+    if (!securitySchemes || Object.keys(securitySchemes).length === 0) {
+        return;
+    }
+    openapi.components = openapi.components || {};
+    openapi.components.securitySchemes = {
+        ...(openapi.components.securitySchemes ?? {}),
+        ...securitySchemes,
+    };
 };
-const mergePathItem = (paths, normalizedPathKey, pathItem) => {
-  const targetPath = paths[normalizedPathKey] ?? {};
-  for (const [key, value] of Object.entries(pathItem)) {
-    if (value === void 0) {
-      continue;
-    }
-    const isOperationKey = OPERATION_KEYS.includes(key);
-    if (isOperationKey && targetPath[key]) {
-      const operationName = typeof key === "string" ? key.toUpperCase() : String(key);
-      console.warn(
-        `Duplicate operation detected for ${operationName} ${normalizedPathKey}. Last operation will overwrite previous.`
-      );
-    }
-    targetPath[key] = value;
-  }
-  paths[normalizedPathKey] = targetPath;
+const mergeServerLists = (existing, incoming) => {
+    const seen = new Set((existing ?? []).map((s) => s.url));
+    const out = [...(existing ?? [])];
+    for (const server of incoming) {
+        if (!seen.has(server.url)) {
+            seen.add(server.url);
+            out.push(server);
+        }
+    }
+    return out;
 };
-const cleanupOperations = (paths) => {
-  Object.values(paths).forEach((pathItem) => {
-    if (!pathItem) {
-      return;
+const mergeTagsIntoDocument = (openapi, incoming) => {
+    if (incoming.length === 0) {
+        return;
     }
-    OPERATION_KEYS.forEach((operationKey) => {
-      const operation = pathItem[operationKey];
-      if (!operation) {
+    const existing = openapi.tags ?? [];
+    if (existing.length === 0) {
+        openapi.tags = incoming;
         return;
-      }
-      if ("parameters" in operation && operation.parameters?.length === 0) {
-        delete operation.parameters;
-      }
-      if ("requestBody" in operation && operation.requestBody && "content" in operation.requestBody) {
-        const content = operation.requestBody.content;
-        if (content && "text/plain" in content) {
-          const text = content["text/plain"];
-          if (!text?.schema || text.schema && Object.keys(text.schema).length === 0) {
-            content["text/plain"] = {};
-          }
-        }
-      }
-      if (!operation.description) {
-        delete operation.description;
-      }
-    });
-  });
+    }
+    const names = new Set(existing.map((t) => t.name));
+    const additions = incoming.filter((t) => t.name && !names.has(t.name));
+    openapi.tags = additions.length > 0 ? [...existing, ...additions] : existing;
 };
-function convert(postmanCollection) {
-  const collection = validateCollectionShape(parseCollectionInput(postmanCollection));
-  const title = collection.info.name || "API";
-  const version = collection.variable?.find((v) => v.key === "version")?.value || "1.0.0";
-  const description = normalizeDescription(collection.info.description) || "";
-  const license = processLicense(collection);
-  const contact = processContact(collection);
-  const logo = processLogo(collection);
-  const openapi = {
-    openapi: "3.1.0",
-    info: {
-      title,
-      version,
-      ...description && { description },
-      ...license && { license },
-      ...contact && { contact },
-      ...logo && { "x-logo": logo }
-    },
-    paths: {}
-  };
-  const externalDocs = processExternalDocs(collection);
-  if (externalDocs) {
-    openapi.externalDocs = externalDocs;
-  }
-  if (collection.auth) {
-    const { securitySchemes, security } = processAuth(collection.auth);
-    mergeSecuritySchemes(openapi, securitySchemes);
-    openapi.security = security;
-  }
-  const allServerUsage = [];
-  if (collection.item) {
-    const tags = extractTags(collection.item);
-    if (tags.length > 0) {
-      openapi.tags = tags;
-    }
-    collection.item.forEach((item) => {
-      const { paths: itemPaths, components: itemComponents, serverUsage } = processItem(item);
-      allServerUsage.push(...serverUsage);
-      openapi.paths = openapi.paths || {};
-      for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
-        const normalizedPathKey = normalizePath(pathKey);
+const assignTagsFromPostman = (openapi, tags, isMergingIntoBase) => {
+    if (tags.length === 0) {
+        return;
+    }
+    if (isMergingIntoBase) {
+        mergeTagsIntoDocument(openapi, tags);
+    }
+    else {
+        openapi.tags = tags;
+    }
+};
+const cleanupOperations = (paths) => {
+    Object.values(paths).forEach((pathItem) => {
         if (!pathItem) {
-          continue;
+            return;
         }
-        mergePathItem(openapi.paths, normalizedPathKey, pathItem);
-      }
-      if (itemComponents?.securitySchemes) {
-        mergeSecuritySchemes(openapi, itemComponents.securitySchemes);
-      }
+        OPERATION_KEYS.forEach((operationKey) => {
+            const operation = pathItem[operationKey];
+            if (!operation) {
+                return;
+            }
+            if ('parameters' in operation && operation.parameters?.length === 0) {
+                delete operation.parameters;
+            }
+            if ('requestBody' in operation && operation.requestBody && 'content' in operation.requestBody) {
+                const content = operation.requestBody.content;
+                if (content && 'text/plain' in content) {
+                    const text = content['text/plain'];
+                    if (!text?.schema || (text.schema && Object.keys(text.schema).length === 0)) {
+                        content['text/plain'] = {};
+                    }
+                }
+            }
+            if (!operation.description) {
+                delete operation.description;
+            }
+        });
     });
-  }
-  const allUniquePaths = /* @__PURE__ */ new Set();
-  if (openapi.paths) {
-    for (const pathKey of Object.keys(openapi.paths)) {
-      allUniquePaths.add(pathKey);
-    }
-  }
-  const serverPlacement = analyzeServerDistribution(allServerUsage, allUniquePaths);
-  if (serverPlacement.document.length > 0) {
-    openapi.servers = serverPlacement.document;
-  }
-  if (openapi.paths) {
-    for (const [path, servers] of serverPlacement.pathItems.entries()) {
-      const normalizedPathKey = normalizePath(path);
-      const pathItem = openapi.paths[normalizedPathKey];
-      if (pathItem) {
-        pathItem.servers = servers;
-      }
-    }
-    for (const [path, methods] of serverPlacement.operations.entries()) {
-      const normalizedPathKey = normalizePath(path);
-      const pathItem = openapi.paths[normalizedPathKey];
-      if (!pathItem) {
-        continue;
-      }
-      for (const [method, servers] of methods.entries()) {
-        if (method in pathItem) {
-          const operation = pathItem[method];
-          if (operation && typeof operation === "object" && "responses" in operation) {
-            operation.servers = servers;
-          }
-        }
-      }
-    }
-  }
-  if (openapi.paths) {
-    cleanupOperations(openapi.paths);
-  }
-  if (Object.keys(openapi.components || {}).length === 0) {
-    delete openapi.components;
-  }
-  return pruneDocument(openapi);
-}
-export {
-  convert
 };
-//# sourceMappingURL=convert.js.map
+/**
+ * Converts a Postman Collection to an OpenAPI 3.1.0 document.
+ * This function processes the collection's information, servers, authentication,
+ * and items to create a corresponding OpenAPI structure.
+ */
+export function convert(postmanCollection, options = { mergeOperation: false }) {
+    const { requestIndexPaths, mergeOperation = false, document: baseDocument } = options;
+    const isMergingIntoBase = baseDocument !== undefined;
+    const collection = validateCollectionShape(parseCollectionInput(postmanCollection));
+    // Extract title from collection info, fallback to 'API' if not provided
+    const title = collection.info.name || 'API';
+    // Look for version in collection variables, default to '1.0.0'
+    const version = collection.variable?.find((v) => v.key === 'version')?.value || '1.0.0';
+    // Handle different description formats in Postman
+    const description = normalizeDescription(collection.info.description) || '';
+    // Process license and contact information
+    const license = processLicense(collection);
+    const contact = processContact(collection);
+    // Process logo information
+    const logo = processLogo(collection);
+    // Initialize the OpenAPI document with required fields (or clone a base document to merge into)
+    const openapi = baseDocument ?? {
+        openapi: '3.1.0',
+        info: {
+            title,
+            version,
+            ...(description && { description }),
+            ...(license && { license }),
+            ...(contact && { contact }),
+            ...(logo && { 'x-logo': logo }),
+        },
+        paths: {},
+    };
+    openapi.paths = openapi.paths ?? {};
+    // Process external docs
+    const externalDocs = processExternalDocs(collection);
+    if (externalDocs && (!isMergingIntoBase || !openapi.externalDocs)) {
+        openapi.externalDocs = externalDocs;
+    }
+    // Process authentication if present in the collection
+    if (collection.auth) {
+        const { securitySchemes, security } = processAuth(collection.auth);
+        mergeSecuritySchemes(openapi, securitySchemes);
+        if (security?.length) {
+            if (isMergingIntoBase && openapi.security?.length) {
+                openapi.security = [...openapi.security, ...security];
+            }
+            else {
+                openapi.security = security;
+            }
+        }
+    }
+    // Process each item in the collection and merge into OpenAPI spec
+    const allServerUsage = [];
+    if (collection.item) {
+        const usePathFilter = requestIndexPaths !== undefined;
+        if (usePathFilter) {
+            const uniquePaths = dedupeIndexPaths(requestIndexPaths);
+            const tags = extractTagsForSelectedPaths(collection.item, uniquePaths);
+            assignTagsFromPostman(openapi, tags, isMergingIntoBase);
+            for (const path of uniquePaths) {
+                const node = getNodeAtPath(collection.item, path);
+                if (!node) {
+                    continue;
+                }
+                const parentTags = collectParentTagSegments(collection.item, path);
+                const { paths: itemPaths, components: itemComponents, serverUsage, } = processItem(node, DEFAULT_EXAMPLE_NAME, parentTags, '');
+                allServerUsage.push(...serverUsage);
+                for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
+                    const normalizedPathKey = normalizePath(pathKey);
+                    if (!pathItem) {
+                        continue;
+                    }
+                    mergePathItem(openapi.paths, normalizedPathKey, pathItem, mergeOperation);
+                }
+                if (itemComponents?.securitySchemes) {
+                    mergeSecuritySchemes(openapi, itemComponents.securitySchemes);
+                }
+            }
+        }
+        else {
+            const tags = extractTags(collection.item);
+            assignTagsFromPostman(openapi, tags, isMergingIntoBase);
+            collection.item.forEach((item) => {
+                const { paths: itemPaths, components: itemComponents, serverUsage } = processItem(item, DEFAULT_EXAMPLE_NAME);
+                allServerUsage.push(...serverUsage);
+                openapi.paths = openapi.paths || {};
+                for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
+                    const normalizedPathKey = normalizePath(pathKey);
+                    if (!pathItem) {
+                        continue;
+                    }
+                    mergePathItem(openapi.paths, normalizedPathKey, pathItem, mergeOperation);
+                }
+                if (itemComponents?.securitySchemes) {
+                    mergeSecuritySchemes(openapi, itemComponents.securitySchemes);
+                }
+            });
+        }
+    }
+    // Extract all unique paths from the document
+    const allUniquePaths = new Set();
+    if (openapi.paths) {
+        for (const pathKey of Object.keys(openapi.paths)) {
+            allUniquePaths.add(pathKey);
+        }
+    }
+    // Analyze server distribution and place servers at appropriate levels
+    const serverPlacement = analyzeServerDistribution(allServerUsage, allUniquePaths);
+    // Add servers to document level
+    if (serverPlacement.document.length > 0) {
+        openapi.servers = isMergingIntoBase
+            ? mergeServerLists(openapi.servers, serverPlacement.document)
+            : serverPlacement.document;
+    }
+    // Add servers to path items
+    if (openapi.paths) {
+        for (const [path, servers] of serverPlacement.pathItems.entries()) {
+            const normalizedPathKey = normalizePath(path);
+            const pathItem = openapi.paths[normalizedPathKey];
+            if (pathItem) {
+                pathItem.servers = isMergingIntoBase ? mergeServerLists(pathItem.servers, servers) : servers;
+            }
+        }
+        // Add servers to operations
+        for (const [path, methods] of serverPlacement.operations.entries()) {
+            const normalizedPathKey = normalizePath(path);
+            const pathItem = openapi.paths[normalizedPathKey];
+            if (!pathItem) {
+                continue;
+            }
+            for (const [method, servers] of methods.entries()) {
+                if (method in pathItem) {
+                    const operation = pathItem[method];
+                    if (operation && typeof operation === 'object' && 'responses' in operation) {
+                        operation.servers = isMergingIntoBase ? mergeServerLists(operation.servers, servers) : servers;
+                    }
+                }
+            }
+        }
+    }
+    // Clean up the generated paths
+    if (openapi.paths) {
+        cleanupOperations(openapi.paths);
+    }
+    // Remove empty components object
+    if (Object.keys(openapi.components || {}).length === 0) {
+        delete openapi.components;
+    }
+    return pruneDocument(openapi);
+}