Customizing Request Header description in Swagger

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

Answer 2

TL;DR is that you would have to build your own plugin to do it.

Basically the only out-of-the-box annotations to augment the description in this case are @ApiParam and to be more accurate @ApiImplicitParam. Unfortunately neither of those annotations support descriptions.

So my suggestion would be to:

1. Create your own annotation that would look like this

   @RequestHeader(name = "Api-Key") @Description("Value of license key") String apiKey

NOTE: There is already an annotation in spring that is suitable for this.

2. Create your own ParameterBuilderPlugin
3. Implement the plugin as shown below

public class Test implements ParameterBuilderPlugin {
  @Override
  public void apply(ParameterContext parameterContext) {
    ResolvedMethodParameter methodParameter =parameterContext.resolvedMethodParameter();
    Optional<Description> requestParam = methodParameter.findAnnotation(Description.class);
    if (requestParam.isPresent()) {
      parameterContext.parameterBuilder()
        .description(requestParam.get().value());
    }
  }

  @Override
  public boolean supports(DocumentationType documentationType) {
    return false;
  }
}

4. Pick a value of the order that is is applied after swagger annotations have been processed.

Also please upgrade your springfox library to the latest version.