test: Add test showing how @JsonSubTypes can be used with @Schema-oneOf annotations

[Mattias-Sehlstedt]

Description

TL;DR: I have introduced a test showing how one can circumvent the fact that a @JsonSubtypes will always produce an allOf polymorphic structure (that also breaks if a oneOf @Schema is specified at the same time). This is a reoccurring questions I get, so I would like to collect the solution in a location where it can have two purposes (showing the behavior of the ModelResolver, but also at the same time being a reference that I can share for how to adjust for the scenario).

---

I have many times had discussions regarding how polymorphic models can be constructed/expressed when exposing an OpenApi specification by using springdoc (which relies on swagger-core). Some examples being springdoc/springdoc-openapi#3054 and springdoc/springdoc-openapi#3103.

The scenario is that @JsonSubtypes has to be used to guide Jackson in the deserialization process, but the specification provider prefers to expose the polymorphism with a oneOf structure rather than a allOf structure. My current understanding is that this can be realized by having the parent class own the @JsonSubTypes, while it also implements an interface carrying a @Schema annotation containing a oneOf definition.

My preferred solution would be that it should be configurable whether the @JsonSubTypes is processed (I.e., an explicit @Schema annotation should take precedence over it). I know that this can be realized by providing a custom ModelResolver, but given its current size it is cumbersome to override it. I would have preferred if the ModelResolver had an isolated method responsible for it, so I could just define a ModelResolver that overrides only that method.

I understand that this is a difficult thing to achieve, so thus I elect to add illustrative tests to show the current behavior before I attempt anything. This since it is helpful to add tests for common use-cases even if I do not even introduce any change in behavior with a later PR.

Type of Change

• 🐛 Bug fix
• ✨ New feature
• ♻️ Refactor (non-breaking change)
• 🧪 Tests
• 📝 Documentation
• 🧹 Chore (build or tooling)

Checklist

• I have added/updated tests as needed
• I have added/updated documentation where applicable
• The PR title is descriptive
• The code builds and passes tests locally
• I have linked related issues (if any)

Screenshots / Additional Context

[daniel-kmiecik]

@Mattias-Sehlstedt Just FYI: After making changes in response to code review comments, please leave comments unresolved. The person doing the code review will decide whether your changes are sufficient and will either close them or ask for further changes.

[daniel-kmiecik]

@Mattias-Sehlstedt thanks for the PR — really appreciate your contribution!
Your changes will be available in the next release.

[Mattias-Sehlstedt]

Thanks for your feedback and support @daniel-kmiecik!

@Mattias-Sehlstedt Just FYI: After making changes in response to code review comments, please leave comments unresolved. The person doing the code review will decide whether your changes are sufficient and will either close them or ask for further changes.

Will make sure to do it that way in the future. Is there any preferred way that people generally want to get notified of review comments being acted upon? Or do they generally want to find i themselves (I know that a lot of people ask for a lot of things in these projects). I was thinking for example if it is a difference between a single comment at the end "I have acted upon all review comments" vs one comment/reaction for each review comment.

So far for me email notifications have worked well, but I can imagine it getting out of hand fast.

Edit: I have of course also forgotten the "request review" button that exists, which most likely is what should be used.

[daniel-kmiecik]

@Mattias-Sehlstedt everyone is different and has their own preferences. When we (as maintainers) take action, we give the contributor some time to respond to the code review. The length of time is not set in stone. It depends on many factors.