Schema has the example property, but no exampleRef

[woodgoblin]

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;

[MikeEdgar]

Hi @woodgoblin , thanks for opening this issue. I don't believe OAS supports references to the #/components/examples mapping from schemas, unfortunately. Even in OAS 3.1 where example is deprecated in favor of an array property examples, the entries of the array are the examples themselves.

Are you suggesting some form of pre-processing that would in-line an example from #/components/examples directly to a schema?

[woodgoblin]

Hi @MikeEdgar, if it's the only possible way to solve it then yes.
I would try to dig in more, but given what you had said I still consider it better than inline the JSON that could not be pre-processed in any fashion..

[MikeEdgar]

We discussed this issue on today's MP OpenAPI meetup call. @woodgoblin , have you looked at the possibility of using an example attached to the use of the schema? That might be via the @RequestBody#content or @APIResponse#content attributes, depending on where the schema is referenced.