Problems with generation Java-Code with new 1.4 Release

[tpekeler]

As mentioned in https://github.com/OpenAPITools/openapi-generator#11---compatibility the OpenAPI Spec 3.1 is still im beta.
We run into problems best summed up in OpenAPITools/openapi-generator#18686 .
The inheritance gets not generated correctly.

[cookeac]

I will find a link to an alternative generator that could be investigated. If there is no solution after a few weeks we may need to revert to OpenAPI 3.0.1

[damare]

In my opinion, the code generator works correctly. As I understood from various sources, including https://learn.openapis.org/referencing/overview.html, the functionality of $ref elements pointing to other files corresponds to a classic import in OpenAPI 3.1.

For example, the json object

{ "$ref": "../types/icarIdentifierType.json" }

will be replaced completely by the json object defined in the referenced file.

This means that all references of this kind are now represented as inline objects, which is exactly what we see: no more inheritance and class names that are automatically assigned by the generator.

Since this is part of the basic parsing of the specification files, this is not a generator-specific behavior; as a test, we have tested other generators and see the same issue.

Using a "title" definition for each reference only partially solves the problem: although the corresponding generated classes are then usually named correctly, this does not restore the hierarchy of the data structure. And about naming: Since each reference to the same specification file is rendered as an individual inline object, the generator adds suffixes to each occurrence in order to avoid naming conflicts of the generated classes.

However, using the existing tools to merge spec files did not lead to a solution either. So we have written our own script for that purpose. The resulting specification file then leads to all classes, including inheritance and correct naming. We tested our solution with code generator version 7.9.0-SNAPSHOT.

[mtech-ashelepaev]

Together with Daniel (@damare), we discovered that combining the distributed OpenAPI specification, which is spread across multiple files, into a single file ensures that code generation works as expected.
As a result of combining, we generate a large output schema file that consolidates all components from the separate files. This approach ensures that there are no duplicate objects when the schema is used for code generation and that object names are correctly specified. We have both tried alternative approaches to avoid duplicate classes during code generation, but so far, we have concluded that this is the only solution we have found to work.

The tools which we used to generate schema file:

1. Custom Python tool made by Daniel (@damare).
2. Node.js-based tool @redocly/openapi-cli.

There are several ways to ensure that all partners generate the code consistently:

1. Provide a step-by-step guide on how to create a combined schema file, including the tools used and the specific versions tested and allow partners to generate it themselves.
2. Set up an Azure container with preconfigured tools and grant each partner access to use it for generating the schema.
3. Include the schema in the source control of the ADE and regenerate it each time changes are made to the ADE components.

[cookeac]

Agreed at the meeting Nov 28 2024:

• We like option 3 above - include the combined schema in the ADE repository
• Initially this will be done experimentally and updated each release - but eventually it could be automated.