title: How to enclose Response Entity to a master Template Response in Swagger?
body: <p>My question is related to the one <a href="https://stackoverflow.com/questions/33459644/how-to-specify-a-generic-type-class-for-swagger-api-response" title="posted here">posted here</a>.</p>
  
  <p>I had to rephrase my question as I felt the earlier one was too verbose. Having a go at it again!</p>
  
  <p>I have a REST API which returns a list of Assets, and it's coded like this:</p>
  
  <pre><code>    @GET
      @Produces(MediaType.APPLICATION_JSON)
      public Response getAllAssets() {
          List&lt;Asset&gt; assets = new ArrayList&lt;Asset&gt;();
          for(int i=1; i&lt;11; i++) {
              assets.add(new Asset(i));
          }
  
          return RestResponse.create(Status.OK, "10 assets Fetched successfully!", assets);
      }
  </code></pre>
  
  <p>The response it generates is something like this:</p>
  
  <pre><code>{
      "message":"10 assets Fetched successfully!",
      "content": [{
          "id":"1",
          "type":"LPTP",
          "owner":"Ram",
          "serialNo":"WDKLL3234K3",
          "purchasedOn":"01 Jan 2017"
  
      },
      {
          "id":"2",
          "type":"LPTP",
          "owner":"Ram",
          "serialNo":"WDKLL3234K3",
          "purchasedOn":"01 Jan 2017"
  
      },
      ...
      ]
  }
  </code></pre>
  
  <p>I have over 60 services in my application which follow the same response template:</p>
  
  <pre><code>{
          "message":"Message the service wants to send to the client",
          "content": {
              ....
              Entity returned by the service
              ....
          }
  }
  </code></pre>
  
  <p>The following is the RestResponse POJO that represents our Response Template:</p>
  
  <pre><code> public class RestResponse {
          private String message;
          private Object content;
  
          public String getMessage() {
              return message;
          }
          public void setMessage(String message) {
              this.message = message;
          }
          public Object getContent() {
              return content;
          }
          public void setContent(Object content) {
              this.content = content;
          }
  
          private RestResponse(String message, Object content) {
              this.message = message;
              this.content = content;
          }
  
          public static Response create(Response.Status status, String message, Object content) {
              return Response.status(status).entity(new RestResponse(message, content)).build();
          }
  }
  </code></pre>
  
  <p>Now we're documenting all our APIs using Swagger, and have run into a problem.</p>
  
  <p>Since we're returning the <code>RestResponse</code> class for all our APIs, I wrote the following annotation for my operation:</p>
  
  <pre><code>@ApiOperation(value="Fetches all available assets", response=RestResponse.class, responseContainer="List")
  </code></pre>
  
  <p>What Swagger does, is in the Definition schema for the RestResponse class looks like this:</p>
  
  <pre><code>"definitions": {
      "RestResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "content": {
            "type": "object"
          }
        }
      }
   }
  </code></pre>
  
  <p>Here, I do not get any information or schema about the properties of the object inside the <code>content</code> property. </p>
  
  <p>I understand it's because Swagger doesn't work with Generic Objects.</p>
  
  <p>So if I change my <code>@ApiOperation</code> annotation to the one below:</p>
  
  <pre><code>@ApiOperation(value="Fetches all available assets", response=Asset.class, responseContainer="List")
  </code></pre>
  
  <p>In the above case, Swagger describes the properties of the <code>Asset</code> entity, but obviously, the <code>message</code> property (of my response template), is missing.</p>
  
  <p>My problem is I want to have both. The <code>content</code> property of my response template can be any entity.</p>
  
  <p>So, can I set <code>response=Asset.class</code> and instruct Swagger to enclose <code>Asset</code> to the <code>RestResponse</code> <code>content</code> property before it documents it? Or any other way in which I can achieve this?</p>
  
  <p>Hope I'm precise this time!</p>
  
  <p>Thanks,
  Sriram Sridharan.</p>
  
  <p><strong>Edit - After I tried out Marc Nuri's suggestion</strong>
  I created a similar <code>RestServiceResponse.class</code> with a generic object, and set the <code>responseReference</code> attribute for my <code>@ApiOperation</code> to <code>RestServiceResponse&lt;Asset&gt;</code>. And below is the JSON I got.</p>
  
  <pre><code>{
    "swagger": "2.0",
    "info": {
      "version": "1.0.0",
      "title": ""
    },
    "host": "localhost:7070",
    "basePath": "/assets/rest",
    "tags": [
      {
        "name": "Assets"
      }
    ],
    "schemes": [
      "http"
    ],
    "paths": {
      "/assets/{id}": {
        "get": {
          "tags": [
            "Assets"
          ],
          "summary": "Fetches information about a single asset",
          "description": "",
          "operationId": "fetchAssetDetail",
          "produces": [
            "application/json"
          ],
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "type": "integer",
              "format": "int32"
            }
          ],
          "responses": {
            "200": {
              "description": "successful operation",
              "schema": {
                "$ref": "#/definitions/RestServiceResponse&lt;Asset&gt;"
              }
            }
          }
        }
      }
    }
  }
  </code></pre>
  
  <p>As you can see, the <code>Definitions</code> section is missing altogether. Am I missing something?</p>
  
  <p>I have my <a href="https://github.com/sriramsridharanvr/SwaggerRepo/tree/master/assets" rel="nofollow noreferrer" title="project in GitHub">project in GitHub</a>, in case you need to see the whole code. Please help me.</p>