java - Documenting a wrapped REST response using swagger UI -

i have widgetdto have annotated swagger ui annotations. final response wraps list of widgetdtos layer of metadata (per page 21 of this restful best practices document). example:

{   "data" : [      {       "id" : 1234,       "prop1" : "val1"       ...     },     {       "id" : 5678,       "prop1" : "val2"       ...     },      ...   ] } 

my java code looks this:

@get @produces(mediatype.application_json) @apioperation(         value = "get widgets.",         response = widgetdto.class ) @apiresponses(value = {         @apiresponse(code = 200, message = "returns list of widgets.") }) public response getwidgets() {   list<widgetdto> widgets;   ...   map<string, object> responsebody = new hashmap<>();   responsebody.put("data", widgets);   return response.ok(responsebody).build(); } 

i'd reuse pattern on multiple resources, , don't want create list dtos every response type. there elegant way use swagger document these types of response bodies?

your metadata not part of resource it's part of resource's representation.

in case, responses types 'application/hal+json' and 'application/json', each of them use different wrapper different metadatas. solve problem, created extern document explain these 2 wrappers , each of them, how single resource , list of resources represented metadata.

i think choice correct because separate resource of representations (per page 7 'manipulation of resources through representations' of this restful best practices document)

in case, returns list of widgetdtos, layer of metadata part of representation of resource.

however, can use generic class resource , resources used spring-hateoas :

public class resources<t> implements iterable<t>  {     private final collection<t> content;     resources(iterable<t> content) {         this.content = new arraylist<t>();         (t element : content) {             this.content.add(element);         }     } } 

and use this:

@get @produces(mediatype.application_json) @apioperation(         value = "get widgets.",         response = widgetdto.class ) @apiresponses(value = {         @apiresponse(code = 200, message = "returns list of widgets.") }) public response getwidgets() {   list<widgetdto> widgets;   ...   return response.ok(new resources<widgetdto>(widgets)).build(); }