@JsonSubTypes and oneOf don't work together

[MoellJ]

Describe the bug

It's not possible to generate a polymorphic oneOf schema using @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") and @JsonSubTypes.

I created a test case to showcase my problem and expected behavior: Test case

Description:
I want to generate a polymorphic schema with oneOf (See https://swagger.io/docs/specification/v3_0/data-models/inheritance-and-polymorphism/).
I tried using @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") and @JsonSubTypes annotations for this. However this seems to generate a schema relying on model composition with allOf.
To relieve this, I tried manually adding oneOf info to the @Schema annotation but this produces an invalid schema where the children are missing the type property and there is a circular ´oneOf-allOf` relationship which seems weird (unsure if it's within OpenAPI spec).

If I don't use these jackson annotations and instead add the type property manually to all child classes and manually maintain the parent @Schema annotation content, I get the expected generated schema but I DO want to use jackson. (Workaround is basically this test case test.org.springdoc.api.v30.app243)

To Reproduce

See test case here: https://github.com/MoellJ/springdoc-openapi/blob/3103-showcase-oneOf-problem/springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app244/HelloController.java
(Based on test.org.springdoc.api.v30.app243 )
Issue also exists for v3.1 and doesn't differ as far as I can tell, so I didn't add a test case for this (yet)

Expected behavior

See linked test case above

Additional context
As far as I can tell, this issue is caused by a schema that suffers from the same issue: OpenAPITools/openapi-generator#19261
So evidentially there are some libraries that can not work with this. Unsure if this is an issue on their side or if this is simply not within spec

Possible fixes

1. In case there already is a way to achieve the desired behavior (different config options?): We should add a test case for this and improve documentation
2. Change default generator behavior of @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") and @JsonSubTypes to output polymorphic schema (oneOf) instead of composite schema (allOf) (Will change current behavior)
3. Introduce a config option to manually toggle this behavior between polymorphic and composite
4. Automatically toggle the behavior if a manually added oneOf relationship in the @Schema annotation of the Parent class was detected
5. Other - maintainers probably have better ideas than me

I'd be open to work on this, if we agree on the a solution

[Mattias-Sehlstedt]

Hi @MoellJ, I have encountered and worked with this exact issue. You can read a little bit of background in this thread #2915. I believe I found a semi-working solution, by defining an interface that carried the oneOf, that all children inherited from, and that the actual parent (with the Jackson-annotation) was an abstract class that they inherited from. Then for the actual parent I used @Schema(implements = InterfaceParent).

This would then lead to the deserialization properly going through the parent with the Jackson-annotation, and the class that was introspected and published to the specification had only the oneOf. The drawback to this approach was that it was non-intuitive to maintain and extend, since you had to change it in two places (when you add a new child to the parent, you have to remember to add it to the interface's oneOf-list).

In the end I elected to go with only the Jackson-annotation on the parent (doing a 180 from this comment), since the allOf composite structure technically is almost the exact polymorphic relation of a oneOf. The OpenApi-generator handles it well too. The only thing I noticed that was annoying is that swagger-ui visualizes oneOf better than allOf in their "try-it-out".

What is the background in your case for wanting oneOf over an allOf inheritance? It is technically possible to achieve what we were after, but what makes it difficult is that the allOf-structure comes from swagger-core, which is responsible for most of the Java-class -> OpenApi schema conversion. Back in the day I dreamt of implementing support for this on their end, but given how careful they are about applying changes, I deemed it impossible to be able to be able to do changes there. Inserting an additional custom ModelConverter that goes backwards and removes swagger-core's allOf-structure feels a bit counterintuitive.