Customizing Request Header description in Swagger UI using Springfox-Swagger2

Question

I am using Springfox Swagger2 version 2.4.0, Springfox Swagger UI version 2.4.0 and Swagger Annotations version 1.5.0 in my Spring Boot application.

The question here is, I am able to generate swagger UI for my controller's API and I am able to test the same. But I am not able to specify request header description for my request header. I m using @RequestHeader annotation for the same.

The code snippet in my controller API is follows:

@RequestHeader(name = "Api-Key") String apiKey

The Swagger UI for the request header is as follows:

The highlighted rectangular area in the image represents the description of the request header.

Currently it just picks up the data mentioned in the name attribute and shows it. But i wanna give a different description for the same. i.e. "Value of license key"

How can i achieve this in Swagger UI as @RequestHeader annotation only have value, defaultValue, name and required attributes? Any help would be really appreciated.

Update: Looking for a solution out of the box without any custom annotation of my own

Answer 1

Maybe my answer will help somebody.

As mentioned Dilip Krishnan in his answer you could use io.swagger.annotations.ApiParam or io.swagger.annotations.ApiImplicitParam Swagger annotations for fine-tuned custom documentation.

@ApiParam could be used for registered method parameters.

@ApiImplicitParam could be used if API parameter wasn't registered explicitly.

@RestController
@RequestMapping(value = "/v1/test", produces = "application/json")
@Api(value = "/v1/test")
public class TestController {

    @ApiOperation(value = "Do Something method", tags = "Test method")
    @RequestMapping(value = "/doSomeThing", method = RequestMethod.GET)
    public Foo doSomeThing(
            @ApiParam(value = "Param1 Description", required = true)
            @RequestParam String param) {
        throw new UnsupportedOperationException("do Some Things");
    }

    @ApiOperation(value = "Do Something Another method", tags = "Test method")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "anotherParam1", value = "Another Param1 Description", paramType = "header"),
            @ApiImplicitParam(name = "anotherParam1", value = "Another Param1 Description", paramType = "header")
    })
    @RequestMapping(value = "/doSomeThingAnother", method = RequestMethod.GET)
    public Foo doSomeThingAnother(Bar bar) {
        throw new UnsupportedOperationException("do Some Thing Another");
    }


}    

And in the end you could see following picture