[BUG][spring] schema with both `$ref` and `type: object` sometimes results in `$ref` being ignored

[anthonyvdotbe]

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

For a property like the following:

lifeCycle:
  type: object
  $ref: "LifeCycle"

the generated code might end up using java.lang.Object as the type instead of the generated LifeCycle model.

openapi-generator version

7.24.0

OpenAPI declaration file content or url

openapi.yaml

Generation Details

config.json

Steps to reproduce

• in a directory X, create openapi.yaml and config.json with the contents as above
• from within X, run docker run --rm -v .:/local openapitools/openapi-generator-cli:v7.24.0 generate --strict-spec true --input-spec /local/openapi.yaml --generator-name spring --config /local/config.json --output /local/output
• open the generated BankAccount model: ./output/src/main/java/org/openapitools/model/BankAccount.java

actual: private @Nullable Object lifeCycle = null;
expected: private @Nullable LifeCycle lifeCycle;

Related issues/PRs

#13295

Suggest a fix

Note that the allOf is required to reproduce the bug.

OpenAPINormalizer logs a warning:

[main] WARN o.o.codegen.OpenAPINormalizer - Type(s) cleared (set to null) given $ref is set to #/components/schemas/LifeCycle.

The related issue is not tied to a specific generator, so I assume this issue is generic as well.

[Mattias-Sehlstedt]

Could we please elaborate on the context behind even using

lifeCycle:
  type: object
  $ref: "LifeCycle"

as an OAS structure? I understand that it is "valid" from the linked issue, but in order to be able to determine whether to just drop type: object or to do something else it would be great with some background to why the spec looks like this.

[anthonyvdotbe]

This is a spec that we consume, so I can't provide any context on the why. The given spec is a minimal reproducer for the issue. The actual spec is huge and has dozens of occurrences like that. As the spec is valid, I'm hoping this can be fixed in openapi-generator, rather than having to maintain a customized version of the spec myself.

[Mattias-Sehlstedt]

Have you been in contact with you specification provider and asked them what they mean with this structure? I would not be surprised if they are trying to express a concept that should be expressed in another manner (e.g., if this was to be a way to express typed additionalProperties).

I would definitely be hesitant to use "valid" as an argument in this context. The validator generally only handle syntax and not semantics. So it is always best to ensure that both you and your specification provider are one the same page regarding how specifications work.

This is specifically true in this scenario as we are at a border of functionality. As per the shared reference earlier with "This object cannot be extended with additional properties and any properties added SHALL be ignored." from OAS 3.0.2, this means that $ref takes precedence in 3.0.2 over any other definitions (I would not argue that that makes it so that specification creators can just place junk next to the $ref without introducing noise). in OAS 3.1 this changes and the type: X starts to become a valid an meaningful definition, since siblings are then supported with Schema Objects.

So depending on what specification version that your provider has, it might actually mean something. But I assume it is OAS 3.0.2 since that is what your example is.

Depending on how you openapi-generator job is executed, a simple local solution to handle it is to inject a Normalizer which can manipulate the specification before it is interpreted and made into code.

[anthonyvdotbe]

OpenAPINormalizer already detects the case and logs a warning about it (I updated the OP with it). And in most other cases openapi-generator already handles this correctly. Just in combination with allOf there seems to be a corner case still that isn't handled correctly.

I don't see the difference between OAS 3.0.2 and 3.1.0. In both cases it has the exact same phrase:

This object cannot be extended with additional properties and any properties added SHALL be ignored.

[Mattias-Sehlstedt]

For 3.1 the definition is extended and it also has Note that this restriction on additional properties is a difference between Reference Objects and [Schema Objects](https://spec.openapis.org/oas/v3.1.0.html#schema-object) that contain a $ref keyword.

For OAS 3.0.2, I would expect your structure to be

BankAccount:
  type: object
  lifeCycle:
    $ref: "#/components/schemas/LifeCycle"

rather than

BankAccount:
  allOf:
    - type: object
      properties:
        lifeCycle:
          type: object
          $ref: "#/components/schemas/LifeCycle"

[anthonyvdotbe]

The additional sentence is merely an informative, non-normative note. Regarding the structure, in the actual spec, the allOf has multiple items. I feel the discussion is no longer adding anything new/relevant to the OP. Yes, the spec is suboptimal, but it's valid and openapi-generator already handles a $ref with sibling keys, except in this specific case with allOf. So this issue serves as a bug report to also handle that specific case correctly.