CODEWITHSUNDEEP
spring-bootswaggerswagger-uiswagger-2.0springfox
Gandhi
Gandhi

Reputation: 11935

Customizing Request Header description in Swagger UI using Springfox-Swagger2

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 problem is, I am able to generate swagger UI for my controller's API and I am able to test it, but I am not able to specify request header description for my request header. I'm using @RequestHeader annotation.

Code snippet in my controller API:

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

Swagger UI for the request header:

enter image description here

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

For now, it just picks up the data mentioned in the name attribute and shows it, but I wanna give it a different description, 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.

Upvotes: 12

Views: 35819

Answers (4)

Dmytro Boichenko
Dmytro Boichenko

Reputation: 5407

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

Swagger UI for custom method description

Upvotes: 14

hani
hani

Reputation: 1

Quick, easy valid solution is to use an enum, for example:

@RequestHeader(value = "someval") ALLOWED_VALUES input

private enum ALLOWED_VALUES {A, B, C};

The following will show in swagger: Available values : A, B, C

Upvotes: 0

Boris
Boris

Reputation: 622

We had the same issue, and resolved the problem in the following way:

.. @RequestHeader(value = "..") @ApiParam(value = "Description") String param ..

The idea is to add "description" field into generated swagger. It could look hacky, but it's a quick simple solution which can be useful in your personal case.

Upvotes: 0

Dilip Krishnan
Dilip Krishnan

Reputation: 5487

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.

  1. Create your own ParameterBuilderPlugin
  2. 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;
  }
}
  1. 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.

Upvotes: 4

Related Questions