@scalar/postman-to-openapi 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @scalar/postman-to-openapi
 
+## 0.7.0
+
+### Minor Changes
+
+- [#8904](https://github.com/scalar/scalar/pull/8904): feat: don't keep all headers
+
+### Patch Changes
+
+- [#8901](https://github.com/scalar/scalar/pull/8901): fix fixture generation formatting by writing output textures with 2-space indented JSON so regeneration does not produce noisy diffs when data is unchanged
+- [#8901](https://github.com/scalar/scalar/pull/8901): Move Postman conversion fixtures into the repository and update tests to read local fixture files instead of downloading from cloud storage.
+- [#8899](https://github.com/scalar/scalar/pull/8899): resolve Postman `{{variables}}` in server URLs by substituting collection variable values and emitting OpenAPI server variables when values are unresolved or recursive
+- [#8900](https://github.com/scalar/scalar/pull/8900): fix(postman-to-openapi): preserve tag context when folder description is an empty string
+- [#8900](https://github.com/scalar/scalar/pull/8900): feat(postman-to-openapi): default to leaf-based tag naming with chain fallback option
+- [#8895](https://github.com/scalar/scalar/pull/8895): fix: omit response content for no-body status codes by default
+
+## 0.6.3
+
+### Patch Changes
+
+- [#8903](https://github.com/scalar/scalar/pull/8903): fix: share Postman collection detection from postman-to-openapi
+- [#8902](https://github.com/scalar/scalar/pull/8902): Preserve merged Postman request variants by carrying request-specific examples for parameters and request bodies, unioning status-code responses derived from request names, and concatenating pre-request and post-response script extensions when operations collapse into one path/method.
+- [#8898](https://github.com/scalar/scalar/pull/8898): merge structurally equivalent paths that only differ by path parameter names and align path parameter definitions with the canonical path
+- [#8887](https://github.com/scalar/scalar/pull/8887): fix: invalid json body handling and add root document for bulk operation selection
+- [#8897](https://github.com/scalar/scalar/pull/8897): fix postman-to-openapi response descriptions to use status-aware defaults and parse named examples
+
 ## 0.6.2
 
 ## 0.6.1

package/README.md

@@ -24,6 +24,21 @@ const result = await convert(myPostmanCollection)
 console.log(result)
 ```
 
+### Detect Postman collections
+
+Use `isPostmanCollection` to decide whether an input string should be parsed as a Postman collection before converting.
+
+```ts
+import { convert, isPostmanCollection } from '@scalar/postman-to-openapi'
+
+if (isPostmanCollection(input)) {
+  const openApiDocument = convert(input)
+  console.log(openApiDocument)
+}
+```
+
+`isPostmanCollection` accepts exported collections that do not include `info._postman_id` as long as they contain a valid Postman schema URL and an `item` tree.
+
 ## Community
 
 We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>

package/dist/convert.d.ts

@@ -5,6 +5,7 @@ import type { PostmanCollection } from './types.js';
  * Example: `[0, 2, 1]` → `collection.item[0].item[2].item[1]`.
  */
 export type PostmanRequestIndexPath = readonly number[];
+export type TagNamingStrategy = 'leaf' | 'chain';
 export type ConvertOptions = {
     /**
      * Whether to merge operations with the same path and method.
@@ -21,12 +22,25 @@ export type ConvertOptions = {
      * When omitted, the whole collection is converted (existing behavior).
      */
     requestIndexPaths?: readonly PostmanRequestIndexPath[];
+    /**
+     * Strategy for generating OpenAPI tag names from nested Postman folders.
+     * - `leaf` (default): use the folder name only; duplicate leaves fallback to `parent / leaf`.
+     * - `chain`: keep the legacy full folder chain joined by ` > `.
+     */
+    tagNamingStrategy?: TagNamingStrategy;
     /**
      * 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;
+    /**
+     * Header keys (case-insensitive) to preserve as `parameters[in=header]` even
+     * if they match the built-in block-list of transport, content-negotiation, or
+     * auth headers (Accept, Content-Type, Authorization, Host, ...). Rarely needed —
+     * useful when an API intentionally documents a non-standard use of these names.
+     */
+    keepHeaders?: readonly string[];
 };
 /**
  * Converts a Postman Collection to an OpenAPI 3.1.0 document.

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;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"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAoBxD,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAE9E;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,MAAM,EAAE,CAAA;AA6DvD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAA;AA6rBhD,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,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAA;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,iBAAiB,EAAE,iBAAiB,GAAG,MAAM,EAC7C,OAAO,GAAE,cAA0C,GAClD,WAAW,CAAC,QAAQ,CAkOtB"}

package/dist/convert.js

@@ -4,10 +4,10 @@ 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 { POSTMAN_EXAMPLE_NAME_EXTENSION, POSTMAN_FOLDER_SEGMENTS_EXTENSION, POSTMAN_POST_RESPONSE_SCRIPTS_EXTENSION, POSTMAN_PRE_REQUEST_SCRIPTS_EXTENSION, 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';
+import { createCollectionVariableLookup, getPathStructuralSignature, normalizePath } from './helpers/urls.js';
 const normalizeDescription = (description) => {
     if (typeof description === 'string') {
         return description;
@@ -53,35 +53,173 @@ const validateCollectionShape = (collection) => {
     }
     return candidate;
 };
-/**
- * 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 TAG_CHAIN_SEPARATOR = ' > ';
+const TAG_DUPLICATE_SEPARATOR = ' / ';
+const getTagContextKey = (segments) => JSON.stringify(segments);
+const getChainTagName = (segments) => segments.join(TAG_CHAIN_SEPARATOR);
+const isPathParameterSegment = (segment) => (segment.startsWith('{') && segment.endsWith('}')) || segment.startsWith(':');
+const normalizeLeafTagSegment = (segment) => {
+    const trimmed = segment.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    // Postman folders are sometimes literal URL templates (`/languages/{languageCode}`).
+    // Keep tag names short by turning those into a readable leaf identifier.
+    const looksLikePathTemplate = trimmed.startsWith('/') || (trimmed.includes('/') && !trimmed.includes(' '));
+    if (!looksLikePathTemplate) {
+        return trimmed;
+    }
+    const segments = trimmed
+        .split('/')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (segments.length === 0) {
+        return trimmed;
+    }
+    const preferredSegment = [...segments].reverse().find((part) => !isPathParameterSegment(part));
+    const fallbackSegment = preferredSegment ?? segments[segments.length - 1] ?? trimmed;
+    if (fallbackSegment.startsWith('{') && fallbackSegment.endsWith('}')) {
+        return fallbackSegment.slice(1, -1);
+    }
+    if (fallbackSegment.startsWith(':')) {
+        return fallbackSegment.slice(1);
+    }
+    return fallbackSegment;
+};
+const getLeafTagName = (segments) => normalizeLeafTagSegment(segments[segments.length - 1] ?? '');
+const getLeafDuplicateFallback = (segments, leafTagName) => {
+    const parentSegment = segments[segments.length - 2];
+    if (!parentSegment) {
+        return getChainTagName(segments);
+    }
+    const normalizedParent = normalizeLeafTagSegment(parentSegment);
+    if (!normalizedParent) {
+        return getChainTagName(segments);
+    }
+    return `${normalizedParent}${TAG_DUPLICATE_SEPARATOR}${leafTagName}`;
+};
+const buildLeafTagContextDescription = (segments) => {
+    if (segments.length <= 1) {
+        return undefined;
+    }
+    return `Part of ${segments.slice(0, -1).join(' -> ')}`;
+};
+const mergeTagDescriptions = (description, contextDescription) => {
+    if (description && contextDescription) {
+        return `${description}\n\n${contextDescription}`;
+    }
+    return description || contextDescription;
+};
+const dedupeTagContexts = (contexts) => {
+    const contextMap = new Map();
+    contexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const existing = contextMap.get(key);
+        if (!existing) {
+            contextMap.set(key, context);
+            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))];
+        if (!existing.description && context.description) {
+            contextMap.set(key, context);
+        }
+    });
+    return [...contextMap.values()];
+};
+const resolveTagNameMap = (contexts, strategy) => {
+    const nameMap = new Map();
+    contexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const initialName = strategy === 'chain' ? getChainTagName(context.segments) : getLeafTagName(context.segments);
+        nameMap.set(key, initialName || getChainTagName(context.segments));
+    });
+    if (strategy === 'chain') {
+        return nameMap;
+    }
+    const initialCounts = new Map();
+    nameMap.forEach((name) => {
+        initialCounts.set(name, (initialCounts.get(name) ?? 0) + 1);
+    });
+    contexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const currentName = nameMap.get(key);
+        if (!currentName) {
+            return;
+        }
+        if ((initialCounts.get(currentName) ?? 0) > 1) {
+            nameMap.set(key, getLeafDuplicateFallback(context.segments, currentName));
+        }
+    });
+    const fallbackCounts = new Map();
+    nameMap.forEach((name) => {
+        fallbackCounts.set(name, (fallbackCounts.get(name) ?? 0) + 1);
+    });
+    contexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const currentName = nameMap.get(key);
+        if (!currentName) {
+            return;
+        }
+        if ((fallbackCounts.get(currentName) ?? 0) > 1) {
+            nameMap.set(key, getChainTagName(context.segments));
+        }
+    });
+    return nameMap;
+};
+const buildTagMetadata = (contexts, strategy) => {
+    const uniqueContexts = dedupeTagContexts(contexts);
+    const resolvedNameMap = resolveTagNameMap(uniqueContexts, strategy);
+    const tags = [];
+    const seenNames = new Set();
+    uniqueContexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const name = resolvedNameMap.get(key);
+        if (!name || seenNames.has(name)) {
+            return;
+        }
+        seenNames.add(name);
+        const contextDescription = strategy === 'leaf' ? buildLeafTagContextDescription(context.segments) : undefined;
+        const description = mergeTagDescriptions(context.description, contextDescription);
+        tags.push({
+            name,
+            ...(description && { description }),
+        });
+    });
+    const resolveTagName = (segments) => {
+        if (segments.length === 0) {
+            return undefined;
+        }
+        const fromMap = resolvedNameMap.get(getTagContextKey(segments));
+        if (fromMap) {
+            return fromMap;
+        }
+        if (strategy === 'chain') {
+            return getChainTagName(segments);
+        }
+        return getLeafTagName(segments) || getChainTagName(segments);
     };
-    return items.flatMap((item) => collectTags(item));
+    return { tags, resolveTagName };
 };
+const collectTagContexts = (items, parentSegments = []) => items.flatMap((item) => {
+    if (!isItemGroup(item)) {
+        return [];
+    }
+    const nextSegments = item.name ? [...parentSegments, item.name] : parentSegments;
+    const currentContext = item.name?.length
+        ? [
+            {
+                segments: nextSegments,
+                description: normalizeDescription(item.description),
+            },
+        ]
+        : [];
+    return [...currentContext, ...collectTagContexts(item.item, nextSegments)];
+});
+const extractTags = (items, strategy) => buildTagMetadata(collectTagContexts(items), strategy);
 /**
- * Folder tags for ancestors of each selected path only (same shape as {@link extractTags}).
+ * Folder tags for ancestors of each selected path only (same shape as full extraction).
  */
-const extractTagsForSelectedPaths = (items, paths) => {
+const extractTagContextsForSelectedPaths = (items, paths) => {
     const seen = new Set();
     const result = [];
     for (const path of paths) {
@@ -89,7 +227,7 @@ const extractTagsForSelectedPaths = (items, paths) => {
             continue;
         }
         let list = items;
-        let parentPath = '';
+        const segments = [];
         for (let i = 0; i < path.length - 1; i++) {
             const idx = path[i];
             if (idx === undefined || idx < 0 || idx >= list.length) {
@@ -99,21 +237,23 @@ const extractTagsForSelectedPaths = (items, paths) => {
             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 }),
-                });
+            if (node.name?.length) {
+                segments.push(node.name);
+                const key = getTagContextKey(segments);
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    result.push({
+                        segments: [...segments],
+                        description: normalizeDescription(node.description),
+                    });
+                }
             }
-            parentPath = nextPath;
             list = node.item;
         }
     }
     return result;
 };
+const extractTagsForSelectedPaths = (items, paths, strategy) => buildTagMetadata(extractTagContextsForSelectedPaths(items, paths), strategy);
 const getNodeAtPath = (items, path) => {
     if (path.length === 0) {
         return undefined;
@@ -178,11 +318,13 @@ const mergeSecuritySchemes = (openapi, securitySchemes) => {
     };
 };
 const mergeServerLists = (existing, incoming) => {
-    const seen = new Set((existing ?? []).map((s) => s.url));
+    const createServerKey = (server) => JSON.stringify(server);
+    const seen = new Set((existing ?? []).map(createServerKey));
     const out = [...(existing ?? [])];
     for (const server of incoming) {
-        if (!seen.has(server.url)) {
-            seen.add(server.url);
+        const serverKey = createServerKey(server);
+        if (!seen.has(serverKey)) {
+            seen.add(serverKey);
             out.push(server);
         }
     }
@@ -237,8 +379,199 @@ const cleanupOperations = (paths) => {
             if (!operation.description) {
                 delete operation.description;
             }
+            // Internal merge bookkeeping should not leak in final OpenAPI output.
+            delete operation[POSTMAN_EXAMPLE_NAME_EXTENSION];
+            delete operation[POSTMAN_PRE_REQUEST_SCRIPTS_EXTENSION];
+            delete operation[POSTMAN_POST_RESPONSE_SCRIPTS_EXTENSION];
+            delete operation[POSTMAN_FOLDER_SEGMENTS_EXTENSION];
+        });
+    });
+};
+const getOrderedPathParameterNames = (path) => normalizePath(path)
+    .split('/')
+    .flatMap((segment) => {
+    const match = segment.match(/^\{([^{}]+)\}$/);
+    return match?.[1] ? [match[1]] : [];
+});
+const rewritePathParameterNames = (path, parameterNames) => {
+    const segments = normalizePath(path).split('/');
+    let parameterIndex = 0;
+    const rewrittenSegments = segments.map((segment) => {
+        if (!/^\{[^{}]+\}$/.test(segment)) {
+            return segment;
+        }
+        const canonicalName = parameterNames[parameterIndex];
+        parameterIndex += 1;
+        return canonicalName ? `{${canonicalName}}` : segment;
+    });
+    return rewrittenSegments.join('/');
+};
+const chooseMostCommonName = (names) => {
+    if (names.length === 0) {
+        return undefined;
+    }
+    const counts = new Map();
+    const firstIndex = new Map();
+    names.forEach((name, index) => {
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+        if (!firstIndex.has(name)) {
+            firstIndex.set(name, index);
+        }
+    });
+    return [...counts.entries()].sort((a, b) => {
+        if (a[1] !== b[1]) {
+            return b[1] - a[1];
+        }
+        return (firstIndex.get(a[0]) ?? Number.POSITIVE_INFINITY) - (firstIndex.get(b[0]) ?? Number.POSITIVE_INFINITY);
+    })[0]?.[0];
+};
+const renameParameters = (parameters, renameMap) => {
+    if (!parameters || renameMap.size === 0) {
+        return parameters;
+    }
+    const mergedParameters = new Map();
+    parameters.forEach((parameter, index) => {
+        if (!parameter || '$ref' in parameter) {
+            mergedParameters.set(`$ref/${index}`, parameter);
+            return;
+        }
+        const nextName = parameter.in === 'path' ? (renameMap.get(parameter.name) ?? parameter.name) : parameter.name;
+        const renamedParameter = nextName === parameter.name ? parameter : { ...parameter, name: nextName };
+        const parameterKey = `${renamedParameter.name}/${renamedParameter.in}`;
+        const existingParameter = mergedParameters.get(parameterKey);
+        if (!existingParameter || '$ref' in existingParameter || '$ref' in renamedParameter) {
+            mergedParameters.set(parameterKey, renamedParameter);
+            return;
+        }
+        mergedParameters.set(parameterKey, {
+            ...existingParameter,
+            ...renamedParameter,
+            examples: {
+                ...(existingParameter.examples ?? {}),
+                ...(renamedParameter.examples ?? {}),
+            },
+        });
+    });
+    return [...mergedParameters.values()];
+};
+const renamePathParametersForOperation = (operation, renameMap) => {
+    if (!operation.parameters || renameMap.size === 0) {
+        return operation;
+    }
+    return {
+        ...operation,
+        parameters: renameParameters(operation.parameters, renameMap),
+    };
+};
+const renamePathItemParameterNames = (pathItem, sourceNames, targetNames) => {
+    const renameMap = new Map();
+    sourceNames.forEach((sourceName, index) => {
+        const targetName = targetNames[index];
+        if (sourceName && targetName && sourceName !== targetName) {
+            renameMap.set(sourceName, targetName);
+        }
+    });
+    if (renameMap.size === 0) {
+        return pathItem;
+    }
+    const renamedPathItem = {
+        ...pathItem,
+        parameters: renameParameters(pathItem.parameters, renameMap),
+    };
+    OPERATION_KEYS.forEach((operationKey) => {
+        const operation = pathItem[operationKey];
+        if (!operation) {
+            return;
+        }
+        renamedPathItem[operationKey] = renamePathParametersForOperation(operation, renameMap);
+    });
+    return renamedPathItem;
+};
+const findFolderTemplateHint = (pathItemGroup, signature) => {
+    for (const { pathItem, parameterNames } of pathItemGroup) {
+        for (const operationKey of OPERATION_KEYS) {
+            const operation = pathItem[operationKey];
+            if (!operation) {
+                continue;
+            }
+            // Use the raw Postman folder chain if available; otherwise fall back to
+            // splitting tag strings (supports the legacy chain tag naming strategy).
+            const rawSegments = operation[POSTMAN_FOLDER_SEGMENTS_EXTENSION];
+            const folderNameCandidates = rawSegments ? [...rawSegments] : [];
+            for (const tag of operation.tags ?? []) {
+                folderNameCandidates.push(...tag.split(' > ').map((segment) => segment.trim()));
+            }
+            for (const folderName of folderNameCandidates) {
+                if (!folderName.startsWith('/')) {
+                    continue;
+                }
+                const normalizedFolderName = normalizePath(folderName);
+                if (getPathStructuralSignature(normalizedFolderName) !== signature) {
+                    continue;
+                }
+                const folderParameterNames = getOrderedPathParameterNames(normalizedFolderName);
+                if (folderParameterNames.length === parameterNames.length) {
+                    return folderParameterNames;
+                }
+            }
+        }
+    }
+    return undefined;
+};
+const unifyEquivalentPathParameters = (paths) => {
+    const pathEntries = Object.entries(paths).filter((entry) => Boolean(entry[1]));
+    const groups = new Map();
+    pathEntries.forEach(([pathKey, pathItem]) => {
+        const signature = getPathStructuralSignature(pathKey);
+        if (!groups.has(signature)) {
+            groups.set(signature, []);
+        }
+        groups.get(signature)?.push({
+            pathKey,
+            pathItem,
+            parameterNames: getOrderedPathParameterNames(pathKey),
+        });
+    });
+    const unifiedPaths = {};
+    const canonicalPathByPath = new Map();
+    const processedPathKeys = new Set();
+    pathEntries.forEach(([pathKey]) => {
+        if (processedPathKeys.has(pathKey)) {
+            return;
+        }
+        const signature = getPathStructuralSignature(pathKey);
+        const group = groups.get(signature) ?? [];
+        if (group.length < 2) {
+            const pathItem = paths[pathKey];
+            if (pathItem) {
+                unifiedPaths[pathKey] = pathItem;
+                canonicalPathByPath.set(pathKey, pathKey);
+            }
+            processedPathKeys.add(pathKey);
+            return;
+        }
+        const firstGroupEntry = group[0];
+        if (!firstGroupEntry || firstGroupEntry.pathKey !== pathKey) {
+            return;
+        }
+        const parameterCount = firstGroupEntry.parameterNames.length;
+        const folderTemplateHint = findFolderTemplateHint(group, signature);
+        const canonicalParameterNames = folderTemplateHint ??
+            Array.from({ length: parameterCount }, (_, parameterIndex) => {
+                const namesInOrder = group
+                    .map((entry) => entry.parameterNames[parameterIndex])
+                    .filter((name) => Boolean(name));
+                return chooseMostCommonName(namesInOrder) ?? namesInOrder[0] ?? '';
+            });
+        const canonicalPath = rewritePathParameterNames(firstGroupEntry.pathKey, canonicalParameterNames);
+        group.forEach(({ pathKey: groupedPathKey, pathItem, parameterNames }) => {
+            const normalizedPathItem = renamePathItemParameterNames(pathItem, parameterNames, canonicalParameterNames);
+            mergePathItem(unifiedPaths, canonicalPath, normalizedPathItem, true);
+            canonicalPathByPath.set(groupedPathKey, canonicalPath);
+            processedPathKeys.add(groupedPathKey);
         });
     });
+    return { paths: unifiedPaths, canonicalPathByPath };
 };
 /**
  * Converts a Postman Collection to an OpenAPI 3.1.0 document.
@@ -246,7 +579,7 @@ const cleanupOperations = (paths) => {
  * and items to create a corresponding OpenAPI structure.
  */
 export function convert(postmanCollection, options = { mergeOperation: false }) {
-    const { requestIndexPaths, mergeOperation = false, document: baseDocument } = options;
+    const { requestIndexPaths, mergeOperation = false, tagNamingStrategy = 'leaf', document: baseDocument, keepHeaders, } = options;
     const isMergingIntoBase = baseDocument !== undefined;
     const collection = validateCollectionShape(parseCollectionInput(postmanCollection));
     // Extract title from collection info, fallback to 'API' if not provided
@@ -294,11 +627,12 @@ export function convert(postmanCollection, options = { mergeOperation: false })
     }
     // Process each item in the collection and merge into OpenAPI spec
     const allServerUsage = [];
+    const collectionVariableLookup = createCollectionVariableLookup(collection.variable);
     if (collection.item) {
         const usePathFilter = requestIndexPaths !== undefined;
         if (usePathFilter) {
             const uniquePaths = dedupeIndexPaths(requestIndexPaths);
-            const tags = extractTagsForSelectedPaths(collection.item, uniquePaths);
+            const { tags, resolveTagName } = extractTagsForSelectedPaths(collection.item, uniquePaths, tagNamingStrategy);
             assignTagsFromPostman(openapi, tags, isMergingIntoBase);
             for (const path of uniquePaths) {
                 const node = getNodeAtPath(collection.item, path);
@@ -306,7 +640,7 @@ export function convert(postmanCollection, options = { mergeOperation: false })
                     continue;
                 }
                 const parentTags = collectParentTagSegments(collection.item, path);
-                const { paths: itemPaths, components: itemComponents, serverUsage, } = processItem(node, DEFAULT_EXAMPLE_NAME, parentTags, '');
+                const { paths: itemPaths, components: itemComponents, serverUsage, } = processItem(node, DEFAULT_EXAMPLE_NAME, parentTags, '', mergeOperation, resolveTagName, collectionVariableLookup, keepHeaders);
                 allServerUsage.push(...serverUsage);
                 for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
                     const normalizedPathKey = normalizePath(pathKey);
@@ -321,10 +655,10 @@ export function convert(postmanCollection, options = { mergeOperation: false })
             }
         }
         else {
-            const tags = extractTags(collection.item);
+            const { tags, resolveTagName } = extractTags(collection.item, tagNamingStrategy);
             assignTagsFromPostman(openapi, tags, isMergingIntoBase);
             collection.item.forEach((item) => {
-                const { paths: itemPaths, components: itemComponents, serverUsage } = processItem(item, DEFAULT_EXAMPLE_NAME);
+                const { paths: itemPaths, components: itemComponents, serverUsage, } = processItem(item, DEFAULT_EXAMPLE_NAME, [], '', mergeOperation, resolveTagName, collectionVariableLookup, keepHeaders);
                 allServerUsage.push(...serverUsage);
                 openapi.paths = openapi.paths || {};
                 for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
@@ -341,6 +675,20 @@ export function convert(postmanCollection, options = { mergeOperation: false })
         }
     }
     // Extract all unique paths from the document
+    let canonicalPathByPath = new Map();
+    if (openapi.paths) {
+        const unificationResult = unifyEquivalentPathParameters(openapi.paths);
+        openapi.paths = unificationResult.paths;
+        canonicalPathByPath = unificationResult.canonicalPathByPath;
+    }
+    const normalizedServerUsage = allServerUsage.map((usage) => {
+        const normalizedUsagePath = normalizePath(usage.path);
+        return {
+            ...usage,
+            path: canonicalPathByPath.get(normalizedUsagePath) ?? normalizedUsagePath,
+        };
+    });
+    // Extract all unique paths from the document
     const allUniquePaths = new Set();
     if (openapi.paths) {
         for (const pathKey of Object.keys(openapi.paths)) {
@@ -348,7 +696,7 @@ export function convert(postmanCollection, options = { mergeOperation: false })
         }
     }
     // Analyze server distribution and place servers at appropriate levels
-    const serverPlacement = analyzeServerDistribution(allServerUsage, allUniquePaths);
+    const serverPlacement = analyzeServerDistribution(normalizedServerUsage, allUniquePaths);
     // Add servers to document level
     if (serverPlacement.document.length > 0) {
         openapi.servers = isMergingIntoBase

package/dist/helpers/header-utils.d.ts

@@ -0,0 +1,21 @@
+import type { HeaderList } from '../types.js';
+type RequestHeaders = HeaderList | string | null | undefined;
+/**
+ * Looks up a header value case-insensitively. Returns the value of the first
+ * non-disabled match, or undefined. Silently ignores string-typed headers
+ * (Postman occasionally stores them that way).
+ */
+export declare function readHeader(headers: RequestHeaders, name: string): string | undefined;
+/**
+ * Normalises a raw Content-Type header value (`application/json; charset=utf-8`)
+ * to just the media type (`application/json`). Returns undefined for empty input.
+ */
+export declare function parseMediaType(value: string | undefined): string | undefined;
+/**
+ * Picks a single media type from an Accept header value, preferring
+ * `application/json` if present, else the first non-wildcard type. Returns
+ * undefined for `*​/*` alone, empty input, or only wildcard types.
+ */
+export declare function pickAcceptMediaType(value: string | undefined): string | undefined;
+export {};
+//# sourceMappingURL=header-utils.d.ts.map

package/dist/helpers/header-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-utils.d.ts","sourceRoot":"","sources":["../../src/helpers/header-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,UAAU,EAAE,MAAM,SAAS,CAAA;AAEjD,KAAK,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;AAE5D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOpF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM5E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAYjF"}