Description
Example references are much clearer and much more consistent ways to not desync examples and schemas in generated OpenAPI.
However, if I need to have 3 slightly different examples in a single array in a HUGE DTO, I need to override all of the request/response object JSON because the @Schema property can not contain nor the @ExampleObject, nor the exampleRef, which would allow us to point to the example reference which is checked against its schema class in OAS model filter.
Allowing a DTO field to have a free-form JSON example that 100% would contradict the schema at some point right in the java code, but not allowing the same field to draw from the example references pool OAS model has is pure malice.
To further explain what I mean, I'll have a following example:
Permitted:
@Schema(example = "< unintelligible mess of escaped nonsense no one would ever read or update>")
private Address home;
@Schema(example = "< another unintelligible mess of escaped nonsense no one would ever read or update>")
private Address work;Not permitted:
@Schema(exampleRef = "homeAddressExample") //short ref to the example from a map that is verified to conform to the Address class in a custom OAS filter
private Address home;
@Schema(exampleRef = "workAddressExample")
private Address work;