fix: merge paths with non-conflicting HTTP methods instead of adding prefix

Co-authored-by: mrlubos <12529395+mrlubos@users.noreply.github.com>

Author: Copilot

packages/json-schema-ref-parser/src/__tests__/bundle.test.ts

@@ -308,4 +308,86 @@ describe('bundle', () => {
       }
     });
   });
+
+  describe('mergeMany', () => {
+    it('merges paths with non-conflicting methods under the same path', async () => {
+      const refParser = new $RefParser();
+      const spec1 = {
+        info: { title: 'Spec 1', version: '1.0.0' },
+        paths: {
+          '/pet/{petId}': {
+            post: {
+              operationId: 'updatePetWithForm',
+              responses: { '405': { description: 'Invalid input' } },
+            },
+          },
+        },
+        swagger: '2.0',
+      };
+      const spec2 = {
+        info: { title: 'Spec 2', version: '1.0.0' },
+        paths: {
+          '/pet/{petId}': {
+            delete: {
+              operationId: 'deletePet',
+              responses: {
+                '400': { description: 'Invalid ID supplied' },
+                '404': { description: 'Pet not found' },
+              },
+            },
+          },
+        },
+        swagger: '2.0',
+      };
+
+      const merged = (await refParser.bundleMany({ pathOrUrlOrSchemas: [spec1, spec2] })) as any;
+
+      // Both methods should be under the same path (no prefix added)
+      expect(merged.paths['/pet/{petId}']).toBeDefined();
+      expect(merged.paths['/pet/{petId}'].post).toBeDefined();
+      expect(merged.paths['/pet/{petId}'].delete).toBeDefined();
+
+      // No prefixed path should be created
+      const pathKeys = Object.keys(merged.paths);
+      expect(pathKeys).toHaveLength(1);
+    });
+
+    it('adds prefix to path when HTTP methods conflict', async () => {
+      const refParser = new $RefParser();
+      const spec1 = {
+        info: { title: 'Spec 1', version: '1.0.0' },
+        paths: {
+          '/pet/{petId}': {
+            get: {
+              operationId: 'getPetById',
+              responses: { '200': { description: 'OK' } },
+            },
+          },
+        },
+        swagger: '2.0',
+      };
+      const spec2 = {
+        info: { title: 'Spec 2', version: '1.0.0' },
+        paths: {
+          '/pet/{petId}': {
+            get: {
+              operationId: 'getPet',
+              responses: { '200': { description: 'Success' } },
+            },
+          },
+        },
+        swagger: '2.0',
+      };
+
+      const merged = (await refParser.bundleMany({ pathOrUrlOrSchemas: [spec1, spec2] })) as any;
+
+      // The conflicting path should be prefixed
+      const pathKeys = Object.keys(merged.paths);
+      expect(pathKeys).toHaveLength(2);
+      expect(merged.paths['/pet/{petId}']).toBeDefined();
+      const prefixedKey = pathKeys.find((k) => k !== '/pet/{petId}');
+      expect(prefixedKey).toBeDefined();
+      expect(merged.paths[prefixedKey!].get).toBeDefined();
+    });
+  });
 });

packages/json-schema-ref-parser/src/index.ts

@@ -527,20 +527,44 @@ export class $RefParser {
         }
       }
 
+      const HTTP_METHODS = new Set([
+        'delete',
+        'get',
+        'head',
+        'options',
+        'patch',
+        'post',
+        'put',
+        'trace',
+      ]);
+
       const srcPaths = (schema.paths || {}) as Record<string, any>;
       for (const [p, item] of Object.entries(srcPaths)) {
-        let targetPath = p;
         if (merged.paths[p]) {
-          const trimmed = p.startsWith('/') ? p.substring(1) : p;
-          targetPath = `/${prefix}/${trimmed}`;
+          const newMethods = Object.keys(item as object).filter((k) => HTTP_METHODS.has(k));
+          const hasMethodConflict = newMethods.some((m) => merged.paths[p][m] !== undefined);
+          const rewritten = cloneAndRewrite(
+            item,
+            refMap,
+            tagMap,
+            prefix,
+            url.stripHash(sourcePath),
+          );
+          if (hasMethodConflict) {
+            const trimmed = p.startsWith('/') ? p.substring(1) : p;
+            merged.paths[`/${prefix}/${trimmed}`] = rewritten;
+          } else {
+            Object.assign(merged.paths[p], rewritten);
+          }
+        } else {
+          merged.paths[p] = cloneAndRewrite(
+            item,
+            refMap,
+            tagMap,
+            prefix,
+            url.stripHash(sourcePath),
+          );
         }
-        merged.paths[targetPath] = cloneAndRewrite(
-          item,
-          refMap,
-          tagMap,
-          prefix,
-          url.stripHash(sourcePath),
-        );
       }
     }