OpenAPI: Use oneOf with $ref

[jeengbe]

Is there an existing issue that is already proposing this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe it

I would like to get a named oneOf in /components/schemas and referring to it with $ref instead of inlining all oneOf types.

Advantages of this are numerous. I currently experience working with oneOfs as rather painful. On one hand, you cannot simply use oneOf in the same way you use other models by referring to them with getSchemaPath. Instead, you need to know that the type referred to is a union type.
It also makes working with clients generated from the API documentation more cumbersome. When used to be a nicely named union type, now has to be named like ThingDto['unionField'], or UnionADto | UnionBDto | ....

Describe the solution you'd like

In the example in the docs, this would be creating a PetDto schema for the Pet union type, which is then used like $ref: /components/schemas/PetDto instead of an inline oneOf.

Teachability, documentation, adoption, migration strategy

No response

What is the motivation / use case for changing the behavior?

described above