[REQ] Document gradle plugin incompatibility with swagger codegen

Is your feature request related to a problem? Please describe.

I attempted to use both the Open API generator gradle plugin and Swagger codegen within a single Gradle project, during a transitional phase between the two. When running the Open API generator task in this configuration, it appears to silently use the old Swagger codegen libraries at some level under the hood, resulting in invalid output for OpenAPI 3 inputs.

Describe the solution you'd like

A clear error message in this situation. Or if this is difficult, documentation around this as being a known issue.

Additional context

To reproduce:

• Pull petstore.yaml (3.0) locally in an empty directory
• Setup gradle: gradle wrapper --gradle-version=5.6.3
• Working example build.gradle:

plugins {                                                                                                                                                                      
  id "org.openapi.generator" version "4.3.1"                                                                                                                                   
}                                                                                                                                                                              
                                                                                                                                                                               
openApiGenerate {                                                                                                                                                              
  generatorName = "java"                                                                                                                                                       
  inputSpec = "$projectDir/petstore.yaml"                                                                                                                                      
}       

./gradlew openApiGenerate
head -n 10 build/generate-resources/main/src/main/java/org/openapitools/client/model/Pet.java 
/*
 * Swagger Petstore
 * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
 *
 * The version of the OpenAPI document: 1.0.0
 * 
 *
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
 * https://openapi-generator.tech
 * Do not edit the class manually.

✅ this looks good

Now, add the swagger codegen dependency to simulate the described scenario, new build.gradle:

buildscript {                                                                                                                                                                  
  dependencies {                                                                                                                                                               
    classpath "io.swagger:swagger-codegen:2.2.3"                                                                                                                               
  }                                                                                                                                                                            
}                                                                                                                                                                              
                                                                                                                                                                               
plugins {                                                                                                                                                                      
  id "org.openapi.generator" version "4.3.1"                                                                                                                                   
}                                                                                                                                                                              
                                                                                                                                                                               
openApiGenerate {                                                                                                                                                              
  generatorName = "java"                                                                                                                                                       
  inputSpec = "$projectDir/petstore.yaml"                                                                                                                                      
}    

./gradlew openApiGenerate
head -n 10 build/generate-resources/main/src/main/java/org/openapitools/client/model/Pet.java 
/*
 * Swagger Petstore
 * No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
 *
 * OpenAPI spec version: 1.0.0
 * 
 *
 * NOTE: This class is auto generated by the swagger code generator program.
 * https://github.com/swagger-api/swagger-codegen.git
 * Do not edit the class manually.

❌ The reference to Swagger is unexpected.

Note that this is just a quick validation check - the comment is not the problem. If you look in the file, you can also find invalid Java that doesn't compile, e.g.:

  @SerializedName("id")
  private Long id = ;

Start with the issue's two build.gradle examples and run ./gradlew openApiGenerate against the petstore.yaml input to confirm the differing generated output. Review the project's documentation for Gradle plugin setup and dependency conflicts; done means the OpenAPI Generator and Swagger Codegen incompatibility is clearly documented with the affected configuration and observed failure.