[REQ] maven plugin: remove `generateApis` and `apisToGenerate`

martin-mfg commented 8 months ago

Problem

The openapi-generator-maven-plugin currently has 3 different options to influence which Apis will be generated: generateApis, apisToGenerate and globalProperties.apis. OpenAPI Generator itself only knows about globalProperties.apis. generateApis and apisToGenerate work by openapi-generator-maven-plugin modifying globalProperties.apis.

Some disadvantages with that:

Having 3 options where 1 would be sufficient adds complexity and confusion.
This led to bugs in the past: https://github.com/OpenAPITools/openapi-generator/issues/4506
Setting generateApis=false doesn't actually guarantee that API are not generated. (Specifically when also setting generateModels=false and generateSupportingFiles=false.) related: https://github.com/OpenAPITools/openapi-generator/issues/16257

Proposal

Therefore I propose to remove the options generateApis and apisToGenerate. All the available functionality is accessible by setting globalProperties.apis accordingly.

The same probably also applies to globalProperties.models and globalProperties.supportingFiles.

If this proposal is accepted by a maintainer, I'd be open to work on a PR.

Philzen commented 1 month ago

:thinking: Wouldn't this argument also apply to

generateModels
modelsToGenerate
generateSupportingFiles
supportingFilesToGenerate
generateModelTests
generateModelDocumentation
generateApiTests
generateApiDocumentation
generateRecursiveDependentModels

?

Philzen commented 1 month ago

Actually i wasn't aware of the globalProperties option before i saw your issue, so thanks for that! However i'm getting slightly different results transitioning over to it.

Using

                <configuration>
…
                    <generateModelTests>false</generateModelTests>
                    <generateModelDocumentation>false</generateModelDocumentation>
                    <generateApiTests>false</generateApiTests>
                    <generateApis>false</generateApis>
                    <generateSupportingFiles>false</generateSupportingFiles>
                    <configOptions>
                        <interfaceOnly>true</interfaceOnly>
                    </configOptions>
                </configuration>

will result in the following (nice and concise) output:

[INFO] Processing operation addPet
[INFO] Processing operation getPetById
[INFO] Processing operation deletePet
[INFO] writing file /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/model/Pet.java
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/docs/Pet.md (Skipped by modelDocs options supplied by user.)
[INFO] Skipping generation of APIs.
[INFO] Skipping generation of Webhooks.
[INFO] Skipping generation of supporting files.

While using

                <configuration>
…
                    <globalProperties>
                        <apis>false</apis>
                        <apiTests>false</apiTests>
                        <modelDocs>false</modelDocs>
                        <modelTests>false</modelTests>
                        <supportingFiles>false</supportingFiles>
                    </globalProperties>
                    <configOptions>
                        <interfaceOnly>true</interfaceOnly>
                    </configOptions>
                </configuration>

Will result in the following:

[INFO] Processing operation addPet
[INFO] Processing operation getPetById
[INFO] Processing operation deletePet
[INFO] writing file /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/model/Pet.java
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/docs/Pet.md (Skipped by modelDocs options supplied by user.)
[INFO] Skipping generation of Webhooks.
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/pom.xml (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/README.md (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/build.gradle (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/build.sbt (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/settings.gradle (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/gradle.properties (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/AndroidManifest.xml (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/.travis.yml (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/ApiClient.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/ServerConfiguration.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/ServerVariable.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/.github/workflows/maven.yml (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/api/openapi.yaml (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/gradlew (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/gradlew.bat (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/gradle/wrapper/gradle-wrapper.properties (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/gradle/wrapper/gradle-wrapper.jar (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/git_push.sh (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/.gitignore (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/ApiException.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/Configuration.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/Pair.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/ApiResponse.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/JSON.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/model/AbstractOpenApiSchema.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/src/main/java/org/openapitools/client/RFC3339DateFormat.java (Skipped by supportingFiles options supplied by user.)
[INFO] Skipped /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/.openapi-generator-ignore (Skipped by supportingFiles options supplied by user.)
[INFO] writing file /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/.openapi-generator/VERSION
[INFO] writing file /home/user/prog/oss/openapi-generator/modules/openapi-generator-maven-plugin/src/test/resources/issue-16489/target/generated-sources/issue-16489/.openapi-generator/FILES

which is not only much more verbose output, but generates two files more. Or did i make a mistake defining the equivalent <globalProperties> here?

martin-mfg commented 1 month ago

🤔 Wouldn't this argument also apply to

* `generateModels`

* `modelsToGenerate`

* `generateSupportingFiles`

* `supportingFilesToGenerate`

* `generateModelTests`

* `generateModelDocumentation`

* `generateApiTests`

* `generateApiDocumentation`

* `generateRecursiveDependentModels`

?

Yes, you are right. Good point!

Or did i make a mistake defining the equivalent here?

It's currently not possible. You would have to set <apis>, <apiTests>, etc. to an empty string. Which, surprisingly, is not supported by maven and will be interpreted as null instead (source 1, source 2). So I propose to, as part of this change, make empty string the default value of <apis>, <apiTests>, etc. inside the maven plugin (not in the OpenAPI Generator in general). So users can still "set" empty string by not setting <apis>, <apiTests>, etc. at all. Plus the default behaviour of the maven plugin stays the same as it currently is.

side note: https://openapi-generator.tech/docs/globals says about apis, apiTests, etc.: "Prefer using the more robust .openapi-generator-ignore." We could even consider deprecating apis, apiTests, etc. in favor of always using .openapi-generator-ignore. Although personally wouldn't do this.

OpenAPITools / openapi-generator

[REQ] maven plugin: remove `generateApis` and `apisToGenerate` #16964

Problem

Proposal