A common pattern in OpenAPI specifications, and API design in general, is defining discriminated unions. A proper discriminated union in an OpenAPI specification requires the following:
- A
oneOfmapping for the implementation types. - A
discriminator.propertyNamefor the property that serves as the discriminator. - A
discriminator.mappingfor the mapping of the values of the discriminator to the sub-types.
The code produced by a discriminated union leverages Jackson type mappings to ensure it serializes and (most importantly) de-serialized correctly. An example of the code generated by a properly configured discriminated union can be found here.
Real OpenAPI specifications from real companies exist that either lack #3 or #2 & #3, which results in code that cannot properly be serialized and de-serialized. To correct the issue, this codegen introduces the concept of "Raw" types to handle the issue.
A "Raw" type is an extended HashMap with some extra utility methods. Because it is a HashMap, it is able to be easily serialized and de-serialized no matter what, meaning no errors or lost data. The utility methods around it assist in manually converting this special map to and from an implementation type manually.
Writing code with this obviously requires more boilerplate than a proper discriminated union will. Nevertheless, for an improperly configured specification, this is the best option available.
To see what a "Raw" type union looks like, see the example here. To see examples of working with them, see here.