[BUG][JAVA] When using java and library native I get syntax error

[MoonWalkerAZ]

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?
• [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

When trying to generate .java files from Unleash OpenAPI specs (file attached), I get errors using OpenAPI Generator with java native library. It seems that it generates the method names that are not valid for Java syntax. I use java native because I want the client to be java.net.http.HttpClient.

Command I use:
openapi-generator generate -i unleash.openapi.json -g java -o test --additional-properties=serializationLibrary=jackson,library=native

Example error I get when I try to compile the code:

.../AdvancedPlaygroundRequestSchemaProjects.java:228: error: unexpected token: <
    public List<String> getList<String>() throws ClassCastException {
                               ^

Multiple files have this issue.

openapi-generator version

7.17.0

OpenAPI declaration file content or url

unleash.openapi.json

[Mattias-Sehlstedt]

The issue seems to be this property definition

"projects": {
  "description": "A list of projects to check for toggles in.",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "my-project"
      ],
      "description": "A list of projects to check for toggles in."
    },
    {
      "type": "string",
      "enum": [
        "*"
      ],
      "description": "Check toggles in all projects."
    }
  ]
}

Which has "either list of string or string" within a oneOf. The current mustache definition for oneof_model does not look to handle naming the getter for a collection properly, and thus an invalid < is present in the name

{{#oneOf}}
  /**
  * Get the actual instance of `{{{.}}}`. If the actual instance is not `{{{.}}}`,
  * the ClassCastException will be thrown.
  *
  * @return The actual instance of `{{{.}}}`
  * @throws ClassCastException if the instance is not `{{{.}}}`
  */
  public {{{.}}} get{{{.}}}() throws ClassCastException {
  return ({{{.}}})super.getActualInstance();
}
  
{{/oneOf}}

[MoonWalkerAZ]

Thank you for your response. Will this issue be resolved in the next version of OpenAPI Generator?
Do you have any suggestions on how I can generate a java.net.http.HttpClient with different parameters?

I’ve noticed that this issue doesn’t occur when using the restclient library. However, I can’t use restclient because it generates a Spring RestClient, which isn’t suitable for my use case.

[Mattias-Sehlstedt]

I do not believe it will be fixed. It looks to be a complex issue since the current approach currently assume that the type of the oneOf child can be used as its name. I looked into whether the option generateAliasAsModel could solve it, but it seems that that might not handle objects that are defined within a oneOf.

You could attempt to handle it by adjusting the specification before generating it, and setting the properties to be defined as

components:
  schemas:
    OneOfModel:
      type: object
      properties:
        projects:
          description: A list of projects to check for toggles in.
          oneOf:
            - $ref: '#/components/schemas/StringListAlias'
              description: A list of projects to check for toggles in.
            - type: string
              enum:
                - "*"
              description: Check toggles in all projects.
    StringListAlias:
      type: array
      items:
        type: string
      example:
        - my-project

The key change is then that the list is actually defined as named reference (alias).

This will change the faulty
public List<String> getList<String>() throws ClassCastException {
to
public StringListAlias getStringListAlias() throws ClassCastException {.
But I cannot promise that (de)serialization will work for that approach.

[MoonWalkerAZ]

Thank you for the suggestion, but unfortunately, the structure of OpenAPI specs must remain the same, so the file shouldn't be edited manually. It is interesting that with the parameter library set to restclient, this issue does not occur. Do you know why that is?

[Mattias-Sehlstedt]

the structure of OpenAPI specs must remain the same

Could you elaborate on why this would be set in stone? You would simply be extracting a single definition into a separate section, that would be synonymous with the previous structure from a (de)serialization perspective.

Do you know why that is?

Different libraries implement polymorphism in different ways.

[MoonWalkerAZ]

Could you elaborate on why this would be set in stone? You would simply be extracting a single definition into a separate section, that would be synonymous with the previous structure from a (de)serialization perspective.

The main concern is that each time a new version of the OpenAPI specification is released, the file would need to be manually updated in multiple places (oneOf) whenever the structure changes.

[Mattias-Sehlstedt]

It is possible to define a programmatic solution for adjusting the specification through a normalizer. That makes it highly unlikely that a change in the OpenAPI specification would have an effect on your code generation. But it requires a bit of knowledge to implement one.

Speaking of normalizer, is the endpoint(s) that require this AdvancedPlaygroundRequestSchema class that is unable to be generated an endpoint that you will be using? If not, then it is possible to exclude it from generation with filters from #22128.

[MoonWalkerAZ]

It is possible to define a programmatic solution for adjusting the specification through a normalizer. That makes it highly unlikely that a change in the OpenAPI specification would have an effect on your code generation. But it requires a bit of knowledge to implement one.

Yes, that would be great. Can you please show me how this can be done?

Speaking of normalizer, is the endpoint(s) that require this AdvancedPlaygroundRequestSchema class that is unable to be generated an endpoint that you will be using? If not, then it is possible to exclude it from generation with filters from #22128.

Currently, we’re not using this endpoint (or endpoints), but we plan to in the future. Could you show me an example of how the AdvancedPlaygroundRequestSchema can be excluded from generation?

However, ideally, I’d prefer to handle this with a normalizer instead of excluding schemas.

[jpfinne]

@MoonWalkerAZ

Here are a few working options:

Complex solution: normalizer

You can extends OpenAPINormalizer using NORMALIZER_CLASS and overrides public Schema normalizeSchema(Schema schema, Set<Schema> visitedSchemas)
As mentioned by @Mattias-Sehlstedt it is complex to update your specification so that the code generation works.

Maybe you can just update the schema programmatically to

projects:
  type: object

If so you could just use the schema mapping option below.

Easier solution: schema mapping

--schema-mappings projects=java.lang.Object or --inline-schema-name-mappings

It generates: projects: java.lang.Object;

For json:

"projects" : [ "my-project" ]

the field will be a java.util.List

for json

"projects" : "*"

the field will contain java.lang.String. Use instanceOf in your java code

Complex solution: custom jackson Serialization

--schema-mappings projects=com.myproject.Project

And use jackson features. For example annotate your com.myproject.Project class with Jackson @JSonDeserialize and @JsonSerialize

[Mattias-Sehlstedt]

Could we (as in @MoonWalkerAZ) first just adjust the specification manually with the suggested changes to ensure that this issue is the only one that the generator has with the specification? It could be that this is just one of many issues, and that there are more concepts that the native generator struggle to represent. I would like to avoid trying to forge an "automatic" solution without knowing that it will actually be a solution.

[MoonWalkerAZ]

I changed the JSON with your suggestion (StringListAlias). But still get the same error unexpected token <. Did I change it correctly @Mattias-Sehlstedt ?
unleash.openapi2.json

I also tried the following as suggested by @jpfinne :
unleash.openapi3.json
openapi-generator generate -i unleash.openapi3.json -g java -o test --additional-properties=serializationLibrary=jackson,library=native --schema-mappings projects=java.lang.Object
But still the same error popped up.

[jpfinne]

@MoonWalkerAZ projects is an inline schema under advancedPlaygroundRequestSchema. So you need to use --inline-schema-name-mappings with the correct composite name.

Look at the logs (maybe in verbose mode). You will see the composite name.

[INFO] Inline schema created as advancedPlaygroundRequestSchema_projects. To have complete control of the model name, set the `title` field or use the modelNameMapping option (e.g. --model-name-mappings advancedPlaygroundRequestSchema_projects=NewModel,ModelA=NewModelA in CLI) or inlineSchemaNameMapping option (--inline-schema-name-mappings advancedPlaygroundRequestSchema_projects=NewModel,ModelA=NewModelA in CLI)

[Mattias-Sehlstedt]

I changed the JSON with your suggestion (StringListAlias). But still get the same error unexpected token <. Did I change it correctly @Mattias-Sehlstedt ?

It looks like you changed it correctly, but the specification seem to contain a lot more oneOf definitions where the contents are not objects, so I assume these are also generating invalid code. Given the amount of changes necessary I believe it is unsuitable to attempt to use the normalizer together with aliases. So the inline approach might be the better solution.