Manually define @ApiBodyObject skeleton

[lucaarcangeli]

I'm wandering if is possible to manually define the structure of a request body object. This could be useful in all that cases where REST service not accept a well defined pojo Object but a generic Serializable (i.e. a Map<K, V>). Here's a code snippet to clarify what I mean:

@ApiMethod(verb = ApiVerb.POST, description = "Method description")
@ApiResponseObject(clazz = JSONResponse.class)
@RequestMapping(value = "/xxxx/method", method = RequestMethod.POST, produces = { MediaType.APPLICATION_JSON_VALUE }, consumes = { MediaType.APPLICATION_JSON_VALUE })
public JSONResponse postMethodXXX(HttpServletRequest httpRequest, Locale locale,
    @ApiBodyObject @RequestBody Map<String, Object> jsonEntity) {

    [...]
}

and this is a partial view of the Bootstrap\UI documentation generated:

I pointing out both the response object "JSONResponse" reference (which is itself annotated with @ApiObject annotation so users could inspect his composition into documentation "Objects" section) and the request body object, reported as a generic "map" object. If @ApiBodyObject annotation could also accept a "manually-defined-skeleton" of the request object content pairs (I'm thinking of something similar to @ApiParams and @ApiParam relation) will be amazing. To better understand:

@ApiBodyObject ({
    @ApiBodyParam(name="field1", type="Long", description="..."),
    @ApiBodyParam(name="field2", type="String", description="..."),
    @ApiBodyParam(name="field3", type="MyCustomObject.class", description="...")
})

where MyCustomObject is an @ApiObject annotated class. In my vision this correspond to a JSON object body like:

{
  "field1": 1,
  "field2": "something",
  "field3": {
    "MyCustomObjectField_1": { },
    "MyCustomObjectField_2": { },
    "MyCustomObjectField_n": { }
  }
}

which could be summarized into generated API documentation to better explain the input object.

[fabiomaffioletti]

This would be a really good improvement. Thanks for the suggestion.

[wsdflink]

+1