Modeling Polymorphic Payloads in OpenAPI 3.x with oneOf and a Discriminator
How to model polymorphic request and response bodies in OpenAPI 3.x using oneOf with a discriminator: a worked Pet/Cat/Dog schema, why the mapping table and required property matter, and the pitfalls that break validators and generators.