Make RestApplication class generation configurable

[ch13f0]

#17646
made the generation of a RestApplication class mandatory. This causes an issue when an application has more than one OpenAPI defined endpoint.

For example, with multiple OpenAPI defined endpoints and an existing @ApplicationPath annotated class intended to group those endpoints under a common '/rest' path prefix, using openapi-generator-maven-plugin 7.3.0 or greater will fail to deploy because there will be multiple generated RestApplication class conflicting with the existing @ApplicationPath annotated class:

6-Aug-2024 21:09:58.596 SEVERE [http-nio-8080-exec-4] org.apache.openejb.observer.ObserverManager$MethodInvocation.invoke error invoking org.apache.tomee.webservices.TomeeJaxRsService@2fb68ec6
org.apache.cxf.service.factory.ServiceConstructionException
...
Caused by: org.apache.cxf.service.factory.ServiceConstructionException: There is an endpoint already running on http://localhost:8080/rest.

The mandatory generation of a RestApplication implies a single OpenAPI defined endpoint, and this solipsistic approach means to continue to use an endpoint common path prefix requires one and only one of the defined endpoints to be nominated as the 'chosen one' to define the path prefix;

servers:
  - url: /rest

This is clumsy and non-obvious.
It would be cleaner and more flexible to simply provide a configuration option to disable the RestApplication generation.

[wing328]

to skip a particular file from being generated, what about using .openapi-generator-ignore ?

https://github.com/openapitools/openapi-generator/blob/master/docs/customization.md#ignore-file-format

[ch13f0]

It's a nice idea for a workaround, but it doesn't appear to work.
I've tried various different placements of

<ignoreFileOverride>${project.basedir}/src/main/resources/.openapi-generator-ignore</ignoreFileOverride>

in the openapi-generator-maven-plugin pom.xml configuration, with
RestApplication.java
in .openapi-generator-ignore, but it still yields the generated file.

I'll play about some more.

Edit: Ah, I see https://github.com/openapitools/openapi-generator/blob/master/docs/customization.md#ignore-file-format notes "The .openapi-generator-ignore file must exist in the root of the output directory."

[wing328]

you can also pre-populate the ignore file using the option openapiGeneratorIgnoreList

[ch13f0]

Well I have tried the CLI with
--openapi-generator-ignore-list RestApplication.java
and a manually created .openapi-generator-ignore containing RestApplication.java in the output root and neither suppresses the generation.

I have also tried using using the openapi-generator-maven-plugin and nothing I have tired works.

Does "doNotOverwrite" also apply to 'ignore'?
https://github.com/verhagen/openapi-generator/blob/master/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaJAXRSSpecServerCodegen.java#L209

[wing328]

and a manually created .openapi-generator-ignore containing RestApplication.java in the output root and neither suppresses the generation.

you need to provide the full path to the file

e..g path/to/file_to_be_skip.py

[ch13f0]

Despite the docs saying different?
https://github.com/OpenAPITools/openapi-generator/blob/master/docs/customization.md#ignore-file-format

# This should match build.sh located anywhere.
build.sh

Anyway, I have tried multiple combinations, and nothing seems to achieve the desired result. Maybe I should create a reproducible test case.

[wing328]

the following works for me

java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -g jaxrs-spec -i modules/openapi-generator/src/test/resources/3_0/petstore.yaml -o /tmp/jaxrs --additional-properties interfaceOnly=true  --openapi-generator-ignore-list "src/gen/java/org/openapitools/api/RestApplication.java"

as confirmed by the output log

[main] INFO  o.o.codegen.TemplateManager - writing file C:\Users\wing3\AppData\Local\Temp\jaxrs\README.md
[main] INFO  o.o.codegen.TemplateManager - writing file C:\Users\wing3\AppData\Local\Temp\jaxrs\src\gen\java\org\openapitools\api\RestResourceRoot.java
[main] INFO  o.o.codegen.TemplateManager - writing file C:\Users\wing3\AppData\Local\Temp\jaxrs\pom.xml
[main] INFO  o.o.codegen.TemplateManager - Ignored C:\Users\wing3\AppData\Local\Temp\jaxrs\src\gen\java\org\openapitools\api\RestApplication.java (Ignored by rule in ignore file.)
[main] INFO  o.o.codegen.TemplateManager - writing file C:\Users\wing3\AppData\Local\Temp\jaxrs\src\main\openapi\openapi.yaml
[main] INFO  o.o.codegen.TemplateManager - writing file C:\Users\wing3\AppData\Local\Temp\jaxrs\.openapi-generator\VERSION
[main] INFO  o.o.codegen.TemplateManager - writing file C:\Users\wing3\AppData\Local\Temp\jaxrs\.openapi-generator\FILES

can you please give it a try

This should match build.sh located anywhere.

I always specify the full path so not even aware of this (i wasn't the one who add the ignore file support).

will review and update the documentation accordingly.

my guess is that someone filed a change before which may have changed this documented behavior.

[ch13f0]

Okay, I have some success with the CLI, but it's a relative path, not a full path, and is relative to the output root. If fixing the docs I would be explicit about that. So yes, using the CLI with something like:

java -jar ./openapi-generator-cli-7.6.0.jar generate -g jaxrs-spec -o generated -i ./spec.yaml --additional-properties interfaceOnly=true --openapi-generator-ignore-list src/gen/java/org/openapitools/api/RestApplication.java

does yield:

...
[main] INFO  o.o.codegen.TemplateManager - writing file /openapitest/generated/pom.xml
[main] INFO  o.o.codegen.TemplateManager - Ignored /openapitest/generated/src/gen/java/org/openapitools/api/RestApplication.java (Ignored by rule in ignore file.)
[main] INFO  o.o.codegen.TemplateManager - writing file /openapitest/generated/src/main/openapi/openapi.yaml
...

I thought I had tried all manner of paths including that, but maybe not. Thanks for your patience.

However, our build uses the openapi-generator-maven-plugin, and even given that I could properly specify ignore list in a .openapi-generator-ignore file, the plugin still insists on writing (and presumably using)

target/generated-sources/openapi/.openapi-generator-ignore

and ignores entirely the value of which according to
https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin

specifies the full path to a .openapi-generator-ignore used for pattern based overrides of generated outputs

Am I misinterpreting what that means? How else might I tell the plugin to similarly ignore the generation of RestApplication.java?

[wing328]

can you share your pom.xml?

did you use the openapiGeneratorIgnoreList option in the maven plugin?

(another workaround is simply delete the file via command for example after the code generation process completes)

[ch13f0]

Again, thanks for your patience. I had

<openapiGeneratorIgnoreList>pathToFileToBeIgnoredRelativeToTheGenerationRoot</openapiGeneratorIgnoreList>

as a configOptions. In case anyone else stumbles across this, the correct structure is:

            ...
            <plugin>
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <version>7.6.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>path/to/inputSpec.yaml</inputSpec>
                            <generatorName>jaxrs-spec</generatorName>
                            <apiPackage>com.package.name.api</apiPackage>
                            <modelPackage>com.package.name.model</modelPackage>
                            <openapiGeneratorIgnoreList>path/relative/to/generated-sources/openapi/RestApplication.java</openapiGeneratorIgnoreList>
                            <configOptions>
                                <useTags>true</useTags>
                                <interfaceOnly>true</interfaceOnly>
                                <returnResponse>true</returnResponse>
                                <containerDefaultToNull>false</containerDefaultToNull>
                                <useJakartaEe>true</useJakartaEe>
                                ...
                            </configOptions>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            ...

Obviously, in our case that would mean adding such a line to all the openapi definitions, and as you say we could also have added, say, an ant task to delete the generated file before further compilation, but these are workarounds.

There are a number of comments on #17646 indicating the same issue.

Is it possible to make the generation configurable?

[wing328]

Obviously, in our case that would mean adding such a line to all the openapi definitions

Is it possible to make the generation configurable?

technically we can but still you need to set it (another line in pom.xml) so not much difference than using openapiGeneratorIgnoreList

(we want to avoid adding an option to skip a file or 2 as that would result in too many options per generator)

[ch13f0]

I understand your point, but any workaround needs to be applied to all openapi-defined endpoint pom.xml files as the package and therefore relative paths would be different in each case. A generation configuration could be set in a parent pom.xml.

As it is, the generation assumes that the currently-being-generated endpoint is the sole arbiter of the entire application's path, which is, I would suggest, an unrealistic prospect.