How to add example in an API response without having to describe again the schema?

[gotson]

Hi,

in #2479 it is mentioned that the whole @ApiResponse should be added in order to add an example.

This is not very convenient, given the response code and schema is already introspected from the code.

Isn't there a better way to handle this ?

[Mattias-Sehlstedt]

The issue that you link looks to specifically be for Collections. If your model is represented by an object then the example can be attached to that object (or rather, its Schema) and it can easily be reused.

Could your specific scenario be clarified so it is clearer exactly what type of object that you would like to attach an example to?

[gotson]

My issue is with collections actually. For single objects you are right, adding @Schema with example on the Object class is sufficient.

[gotson]

Ideally for collections, if the object has a schema example, then an example with a collection of 1 item with that example could be generated.

In addition, having a dedicated annotation to provide an example for a collection response without having to use @ApiResponse would be very useful.

[Mattias-Sehlstedt]

Could you provide a minimal specification and an expected json for such a case? It would make it easier to understand the exact scenario, and it would also make it possible to create a test case for which one could try to implement a behavior against.

I might look into the later of the scenarios (example based on object in collection), because I agree with the reasoning behind a collection containing an example if the object has one. I believe that Lists/arrays already work like this, but might be that your case is a more complex collection, like the HashMap that was stated in the issue which you linked?