Provide sample value for request parameter in Swagger

Question

I have a method signature for a rest method in a Spring-Boot RestController that looks like this:

@RequestMapping(
        value = "/path",
        method = RequestMethod.POST,
        consumes = MediaType.APPLICATION_JSON_VALUE,
        produces = MediaType.APPLICATION_JSON_VALUE
)
@ApiImplicitParams({
        @ApiImplicitParam(
                name = "message", 
                value = "Message that is sent to the method", 
                required = true, 
                dataType = "string", 
                paramType = "body"
        )
})
public @ResponseBody String receiveMessage(@RequestBody String message) {
    // ...

    return "{\"success\": true}";
}

I would like to provide a "sample" value for the message parameter that is a JSON string (e.g. {"key" : "value"}). Does anybody know how I can do this using Swagger annotations? I tried

@ApiImplicitParams({
        @ApiImplicitParam(
                // ...
                example = "...JSON value..."
        )
})

but it didn't work. What I would like to have is a "sample value" in the documentation, that the reader can click on to have the parameter value field in the documentation filled with the given sample value. Is this possible?

Here is a screenshot of how it might look like:

Just to prevent "useless" answers: I cannot change the type of the parameter from String to some class type due to my business logic.

Solution 1

Unfortunately you cannot provide an sample or example value for atomic parametera (String, Number, ...).

You can only provide an example if the parameter is an object with a schema, you only have to add an example property to the property description:

properties:
  firstName:
    description: first name
    type: string
    example: John

As a last resort you could add an example value in the parameter's description (value in the ApiImplicitParam annotation).

    @ApiImplicitParam(
            name = "message", 
            value = "Message that is sent to the method. Example: value", 
            required = true, 
            dataType = "string", 
            paramType = "body"
    )

Solution 2

For Spring Boot users, assuming you've a REST method, accepting json body, but for some reasons doesn't explicitly uses @RequestBody. Follow below steps to generate proper Swagger documentation

Update SpringFox configuration bean for additional model

@Bean
public Docket apiDocket() {
     return new Docket(DocumentationType.SWAGGER_2)
             // ...
             .additionalModels(new TypeResolver().resolve(YourRequestModel.class));
}

Update controller API for @ApiImplicitParams

@PostMapping("/your-api")
@ApiOperation(value = "brief description", notes = "Greater details come here")
@ApiImplicitParams({
   @ApiImplicitParam(paramType = "header", name = "x-locale", example = "en"),
   @ApiImplicitParam(paramType = "body", dataType = "YourRequestModel")
})
public YourResponsetModel processRequest() {
   // ...
   return null;
}

This will generate us Swagger with an optional header x-locale, and body of type YourRequestModel.