fix(MergedSpecBuilder): merge path items by HTTP method instead of overwriting on path collision

modules/openapi-generator-cli/src/main/java/org/openapitools/codegen/cmd/Generate.java

@@ -68,6 +68,14 @@ public class Generate extends OpenApiGeneratorCommand {
     @Option(name = "--merged-spec-filename", title = "Name of resulted merged specs file (used along with --input-spec-root-directory option)")
     private String mergedFileName;
 
+    @Option(name = "--merge-conflict-strategy", title = "Merge conflict strategy",
+            description = "Strategy when two specs define the same component/path+method with different definitions: WARN (default, keep first) or FAIL (abort). Only applies with --merge-mode DEEP.")
+    private String mergeConflictStrategy;
+
+    @Option(name = "--merge-mode", title = "Merge mode",
+            description = "How multiple spec files are merged: REF (default, original $ref-based) or DEEP (full inline merge with component deduplication).")
+    private String mergeMode;
+
     @Option(name = {"-t", "--template-dir"}, title = "template directory",
             description = "folder containing the template files")
     private String templateDir;
@@ -346,8 +354,29 @@ public class Generate extends OpenApiGeneratorCommand {
     @Override
     public void execute() {
         if (StringUtils.isNotBlank(inputSpecRootDirectory)) {
-            spec = new MergedSpecBuilder(inputSpecRootDirectory, StringUtils.isBlank(mergedFileName) ? "_merged_spec" : mergedFileName)
-                    .buildMergedSpec();
+            MergedSpecBuilder builder = new MergedSpecBuilder(inputSpecRootDirectory, StringUtils.isBlank(mergedFileName) ? "_merged_spec" : mergedFileName);
+
+            MergedSpecBuilder.MergeMode resolvedMergeMode = MergedSpecBuilder.MergeMode.REF;
+            if (StringUtils.isNotBlank(mergeMode)) {
+                try {
+                    resolvedMergeMode = MergedSpecBuilder.MergeMode.valueOf(mergeMode.toUpperCase(java.util.Locale.ROOT));
+                } catch (IllegalArgumentException e) {
+                    System.err.println("[error] Invalid --merge-mode value '" + mergeMode + "'. Valid values are: REF, DEEP");
+                    return;
+                }
+                builder.withMergeMode(resolvedMergeMode);
+            }
+
+            if (resolvedMergeMode == MergedSpecBuilder.MergeMode.DEEP && StringUtils.isNotBlank(mergeConflictStrategy)) {
+                try {
+                    builder.withConflictStrategy(MergedSpecBuilder.MergeConflictStrategy.valueOf(mergeConflictStrategy.toUpperCase(java.util.Locale.ROOT)));
+                } catch (IllegalArgumentException e) {
+                    System.err.println("[error] Invalid --merge-conflict-strategy value '" + mergeConflictStrategy + "'. Valid values are: WARN, FAIL");
+                    return;
+                }
+            }
+
+            spec = builder.buildMergedSpec();
             System.out.println("Merge input spec would be used - " + spec);
         }
 

modules/openapi-generator-gradle-plugin/README.adoc

@@ -162,8 +162,18 @@ apply plugin: 'org.openapi.generator'
 
 |mergedFileName
 |String / Provider<String>
-|None
-|Name of the file that will contain all merged specs
+|`merged`
+|Name of the output file that will contain all merged specs (used with `inputSpecRootDirectory`)
+
+|mergeMode
+|String / Provider<String>
+|`REF`
+|How multiple spec files are merged. `REF` (default) preserves the original behaviour: generates a lightweight index spec where each path is a `$ref` pointing back to its source file — identical to the master behaviour. `DEEP` fully parses and inlines all paths and components into a single self-contained spec, with component deduplication and conflict detection controlled by `mergeConflictStrategy`.
+
+|mergeConflictStrategy
+|String / Provider<String>
+|`WARN`
+|How to handle name conflicts when `mergeMode` is `DEEP` and two specs define the same component (schema, response, etc.) or the same path+method with different definitions. `WARN` (default) keeps the first definition and logs a warning. `FAIL` throws an exception and aborts the build.
 
 |remoteInputSpec
 |String / Provider<String>
@@ -248,7 +258,7 @@ apply plugin: 'org.openapi.generator'
 |forcedGenerateSchemas
 |List / Provider<List>
 |None
-|Forces generation of the named schemas even when they are listed in `schemaMappings` or `importMappings` (which would normally suppress their generation). The primary use case is producing a *reference copy* of a hand-written class — for example, a custom enum that replaces a generated one — so you can assert in a test that the hand-written version has not diverged from what the generator would produce. List of schema names, e.g. `["MyEnum", "OtherSchema"]`. Use `["*"]` as a wildcard to force-generate *all* schemas that would otherwise be suppressed by a mapping.
+|Forces generation of the named schemas even when they are listed in `schemaMappings` or `importMappings` (which would normally suppress their generation). The primary use case is producing a *reference copy* of a hand-written class — for example, a custom enum that replaces a generated one — so you can assert in a test that the hand-written version has not diverged from what the generator would produce. List of schema names, e.g. `["MyEnum", "OtherSchema"]`. Use `["\*"]` as a wildcard to force-generate *all* schemas that would otherwise be suppressed by a mapping.
 
 |nameMappings
 |Map / Provider<Map>

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/OpenApiGeneratorPlugin.kt

@@ -102,6 +102,9 @@ class OpenApiGeneratorPlugin : Plugin<Project> {
                     inputSpec.set(generate.inputSpec)
                     inputSpecRootDirectory.set(generate.inputSpecRootDirectory)
                     inputSpecRootDirectorySkipMerge.set(generate.inputSpecRootDirectorySkipMerge)
+                    mergedFileName.set(generate.mergedFileName)
+                    mergeMode.set(generate.mergeMode)
+                    mergeConflictStrategy.set(generate.mergeConflictStrategy)
                     remoteInputSpec.set(generate.remoteInputSpec)
                     templateDir.set(generate.templateDir)
                     templateResourcePath.set(generate.templateResourcePath)

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/extensions/OpenApiGeneratorGenerateExtension.kt

@@ -80,6 +80,28 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      */
     val inputSpecRootDirectorySkipMerge = project.objects.property<Boolean>()
 
+    /**
+     * Name of the file that will contain all merged specs (used with inputSpecRootDirectory).
+     *
+     * Default: "merged"
+     */
+    val mergedFileName = project.objects.property<String>()
+
+    /**
+     * How multiple spec files are merged. Accepted values: "REF" (default, original $ref-based
+     * shallow merge, backward-compatible) or "DEEP" (full inline merge with component
+     * deduplication and conflict detection).
+     */
+    val mergeMode = project.objects.property<String>()
+
+    /**
+     * Strategy when two specs define the same component name or path+method with conflicting
+     * (non-identical) definitions. Accepted values: "WARN" (default, keep first definition and
+     * log a warning) or "FAIL" (throw an exception and abort the build). Only applies when
+     * mergeMode is "DEEP".
+     */
+    val mergeConflictStrategy = project.objects.property<String>()
+
     /**
      * The remote Open API 2.0/3.x specification URL location.
      */
@@ -449,6 +471,9 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
     fun applyDefaults() {
         releaseNote.convention("Minor update")
         inputSpecRootDirectorySkipMerge.convention(false)
+        mergedFileName.convention("merged")
+        mergeMode.convention("REF")
+        mergeConflictStrategy.convention("WARN")
         modelNamePrefix.convention("")
         modelNameSuffix.convention("")
         apiNameSuffix.convention("")

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/tasks/GenerateTask.kt

@@ -406,6 +406,23 @@ abstract class GenerateTask : DefaultTask() {
     @get:Optional
     abstract val mergedFileName: Property<String>
 
+    /**
+     * How multiple spec files are merged. Accepted values: "REF" (default, original $ref-based
+     * shallow merge, backward-compatible) or "DEEP" (full inline merge with component
+     * deduplication and conflict detection).
+     */
+    @get:Input
+    @get:Optional
+    abstract val mergeMode: Property<String>
+
+    /**
+     * Strategy when two specs define the same component name or path+method with conflicting
+     * definitions. Accepted values: "WARN" (default) or "FAIL". Only applies when mergeMode is "DEEP".
+     */
+    @get:Input
+    @get:Optional
+    abstract val mergeConflictStrategy: Property<String>
+
     /**
      * The remote Open API 2.0/3.x specification URL location.
      */
@@ -873,6 +890,8 @@ abstract class GenerateTask : DefaultTask() {
     init {
         inputSpecRootDirectorySkipMerge.convention(false)
         mergedFileName.convention("merged")
+        mergeMode.convention("REF")
+        mergeConflictStrategy.convention("WARN")
     }
 
     @Suppress("unused")
@@ -893,10 +912,28 @@ abstract class GenerateTask : DefaultTask() {
 
         inputSpecRootDirectory.orNull?.let { inputDir ->
             if (!inputSpecRootDirectorySkipMerge.get()) {
-                finalResolvedInputSpec = MergedSpecBuilder(
+                val resolvedMergeMode = try {
+                    MergedSpecBuilder.MergeMode.valueOf(mergeMode.get().uppercase())
+                } catch (e: IllegalArgumentException) {
+                    throw GradleException("Invalid mergeMode value '${mergeMode.get()}'. Valid values are: REF, DEEP")
+                }
+
+                val builder = MergedSpecBuilder(
                     inputDir.asFile.absolutePath,
                     mergedFileName.get()
-                ).buildMergedSpec()
+                ).withMergeMode(resolvedMergeMode)
+
+                if (resolvedMergeMode == MergedSpecBuilder.MergeMode.DEEP) {
+                    try {
+                        builder.withConflictStrategy(
+                            MergedSpecBuilder.MergeConflictStrategy.valueOf(mergeConflictStrategy.get().uppercase())
+                        )
+                    } catch (e: IllegalArgumentException) {
+                        throw GradleException("Invalid mergeConflictStrategy value '${mergeConflictStrategy.get()}'. Valid values are: WARN, FAIL")
+                    }
+                }
+
+                finalResolvedInputSpec = builder.buildMergedSpec()
                 logger.info("Merge input spec used: {}", finalResolvedInputSpec)
             }
         }

modules/openapi-generator-gradle-plugin/src/test/resources/specs/petstore-v3.1.yaml

@@ -10,7 +10,7 @@ paths:
   /v3/pets:
     get:
       summary: List all pets
-      operationId: listPets
+      operationId: listPetsV3
       tags:
         - pets
       parameters:
@@ -41,7 +41,7 @@ paths:
                 $ref: "#/components/schemas/Error"
     post:
       summary: Create a pet
-      operationId: createPets
+      operationId: createPetsV3
       tags:
         - pets
       responses:
@@ -56,7 +56,7 @@ paths:
   /v3/pets/{petId}:
     get:
       summary: Info for a specific pet
-      operationId: showPetById
+      operationId: showPetByIdV3
       tags:
         - pets
       parameters:

modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/CodeGenMojo.java

@@ -137,6 +137,22 @@ public class CodeGenMojo extends AbstractMojo {
     @Parameter(name = "mergedFileInfoVersion", property = "openapi.generator.maven.plugin.mergedFileInfoVersion", defaultValue = "1.0.0")
     private String mergedFileInfoVersion;
 
+    /**
+     * Strategy when two specs define the same component name or path+method with different
+     * definitions. Accepted values: WARN (default, keep the first definition and log a warning)
+     * or FAIL (abort the build with an error). Only applies when mergeMode is DEEP.
+     */
+    @Parameter(name = "mergeConflictStrategy", property = "openapi.generator.maven.plugin.mergeConflictStrategy", defaultValue = "WARN")
+    private String mergeConflictStrategy;
+
+    /**
+     * How multiple spec files are merged. Accepted values: REF (default, original $ref-based
+     * shallow merge, backward-compatible) or DEEP (full inline merge with component
+     * deduplication and conflict detection).
+     */
+    @Parameter(name = "mergeMode", property = "openapi.generator.maven.plugin.mergeMode", defaultValue = "REF")
+    private String mergeMode;
+
     /**
      * Git host, e.g. gitlab.com.
      */
@@ -582,9 +598,29 @@ public void execute() throws MojoExecutionException {
             // make sure the path can be processed correct under Windows OS
             inputSpecRootDirectory = inputSpecRootDirectory.replaceAll("\\\\", "/");
 
-            inputSpec = new MergedSpecBuilder(inputSpecRootDirectory, mergedFileName,
+            MergedSpecBuilder.MergeMode resolvedMergeMode;
+            try {
+                resolvedMergeMode = MergedSpecBuilder.MergeMode.valueOf(mergeMode.toUpperCase(Locale.ROOT));
+            } catch (IllegalArgumentException e) {
+                throw new MojoExecutionException("Invalid mergeMode value '" + mergeMode
+                        + "'. Valid values are: REF, DEEP");
+            }
+
+            MergedSpecBuilder builder = new MergedSpecBuilder(inputSpecRootDirectory, mergedFileName,
                     mergedFileInfoName, mergedFileInfoDescription, mergedFileInfoVersion, auth)
-                    .buildMergedSpec();
+                    .withMergeMode(resolvedMergeMode);
+
+            if (resolvedMergeMode == MergedSpecBuilder.MergeMode.DEEP) {
+                try {
+                    builder.withConflictStrategy(
+                            MergedSpecBuilder.MergeConflictStrategy.valueOf(mergeConflictStrategy.toUpperCase(Locale.ROOT)));
+                } catch (IllegalArgumentException e) {
+                    throw new MojoExecutionException("Invalid mergeConflictStrategy value '" + mergeConflictStrategy
+                            + "'. Valid values are: WARN, FAIL");
+                }
+            }
+
+            inputSpec = builder.buildMergedSpec();
             LOGGER.info("Merge input spec would be used - {}", inputSpec);
         }
 

modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/ValidateMojo.java

@@ -127,6 +127,23 @@ public class ValidateMojo extends AbstractMojo {
    */
   @Parameter(name = "mergedFileInfoVersion", property = "openapi.generator.maven.plugin.mergedFileInfoVersion", defaultValue = "1.0.0")
   private String mergedFileInfoVersion;
+
+  /**
+   * Strategy when two specs define the same component name or path+method with different
+   * definitions. Accepted values: WARN (default, keep the first definition and log a warning)
+   * or FAIL (abort the build with an error). Only applies when mergeMode is DEEP.
+   */
+  @Parameter(name = "mergeConflictStrategy", property = "openapi.generator.maven.plugin.mergeConflictStrategy", defaultValue = "WARN")
+  private String mergeConflictStrategy;
+
+  /**
+   * How multiple spec files are merged. Accepted values: REF (default, original $ref-based
+   * shallow merge, backward-compatible) or DEEP (full inline merge with component
+   * deduplication and conflict detection).
+   */
+  @Parameter(name = "mergeMode", property = "openapi.generator.maven.plugin.mergeMode", defaultValue = "REF")
+  private String mergeMode;
+
   /**
    * The path to the collapsed single-file representation of the OpenAPI spec.
    */
@@ -183,10 +200,11 @@ public void execute() throws MojoExecutionException {
       inputSpec = inputSpec[0].split("\\s*,\\s*");
     }
 
-    mergeInDirectory().ifPresent(mergedSpec -> {
+    Optional<String> mergedSpecOpt = mergeInDirectory();
+    if (mergedSpecOpt.isPresent()) {
       inputSpec = new String[1];
-      inputSpec[0] = mergedSpec;
-    });
+      inputSpec[0] = mergedSpecOpt.get();
+    }
 
     try {
       for (String oneInputSpec : inputSpec) {
@@ -244,14 +262,34 @@ private boolean shouldWeSkip() {
     return false;
   }
 
-  private Optional<String> mergeInDirectory() {
+  private Optional<String> mergeInDirectory() throws MojoExecutionException {
     Optional<String> mergedSpec = Optional.empty();
     if (StringUtils.isNotBlank(inputSpecRootDirectory)) {
       inputSpecRootDirectory = replaceBackslashesToSlashes(inputSpecRootDirectory);
 
-      mergedSpec = Optional.of(new MergedSpecBuilder(inputSpecRootDirectory, mergedFileName,
+      MergedSpecBuilder.MergeMode resolvedMergeMode;
+      try {
+        resolvedMergeMode = MergedSpecBuilder.MergeMode.valueOf(mergeMode.toUpperCase(Locale.ROOT));
+      } catch (IllegalArgumentException e) {
+        throw new MojoExecutionException("Invalid mergeMode value '" + mergeMode
+            + "'. Valid values are: REF, DEEP");
+      }
+
+      MergedSpecBuilder builder = new MergedSpecBuilder(inputSpecRootDirectory, mergedFileName,
           mergedFileInfoName, mergedFileInfoDescription, mergedFileInfoVersion, auth)
-          .buildMergedSpec());
+          .withMergeMode(resolvedMergeMode);
+
+      if (resolvedMergeMode == MergedSpecBuilder.MergeMode.DEEP) {
+        try {
+          builder.withConflictStrategy(
+              MergedSpecBuilder.MergeConflictStrategy.valueOf(mergeConflictStrategy.toUpperCase(Locale.ROOT)));
+        } catch (IllegalArgumentException e) {
+          throw new MojoExecutionException("Invalid mergeConflictStrategy value '" + mergeConflictStrategy
+              + "'. Valid values are: WARN, FAIL");
+        }
+      }
+
+      mergedSpec = Optional.of(builder.buildMergedSpec());
       LOGGER.info("Merge input spec would be used - {}", mergedSpec.get());
     }
     return mergedSpec;