How to properly annotate and present a Map type request body?

I’m using springfox-swagger2 2.2.2 with Spring Boot.

One of my REST APIs takes a Map<String, Object> object in request body, like this,

@ApiOperation(
        value = "Submit user data")
@RequestMapping(
        value = "/userData",
        method = RequestMethod.POST,
        consumes = {MediaType.APPLICATION_JSON_VALUE},
        produces = "application/json")
public ResponseEntity<?> submitUserData(
        @RequestBody
        @ApiParam(
            value = "JSON format input, keys allowed are key1, key2, key3."
        ) Map<String, Object> userInput

I want to present the users a sample or the userInput, by default it only shows Model Schema as {} , I’d like to see something like,

{
    "key1":"sample value1",
    "key2":"sample value2",
}

The generated Swagger JSON is as follows,

{
  "in": "body",
  "name": "userInput",
  "description": "JSON format input, keys allowed are key1, key2, key3.",
  "required": false,
  "schema": {
    "type": "object"
  }
}

So here are my main questions based on my understanding,

1. Looks like if I can manage to add additionalProperties into the generated JSON, I should be able to get what I want, a key list for the users to follow. But I’m really not sure how to achieve this with annotations.
2. Seems there is another key called example that can gets me what I want, but not sure how can I use it with Springfox-Swagger.

I think the bottom line is I’m using a Map for request body type instead of having a dedicated class for it, thus I cannot utilize @ApiModel and @ApiModelProperties to customize the documents. Or can I?

[hello-josh]

This is the exact use-case I am trying to solve for: http://stackoverflow.com/questions/41861164/how-can-i-manually-describe-an-example-input-for-a-java-requestbody-mapstring

@RequestMapping(value = "/start", method = RequestMethod.POST)
public void startProcess(
    @ApiParam(examples = @Example(value = {
        @ExampleProperty(
            mediaType="application/json",
            value = "{\"userId\":\"1234\",\"userName\":\"JoshJ\"}"
        )
    }))
    @RequestBody(required = false) Map<String, String> fields) {
    // .. does stuff
}

I couldn’t care less what the user send in, my api is just storing user defined data. What I do care about is being able to document it in swagger ui with some sort of example data, but @ExampleProperty doesn’t seem to work as I understood it from the docs.

[dilipkrish]

@apoorvatarento like this