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

I am confused with RequestHeader exactly as described. ApiParam(name, value, ..) makes sense to me, and #value() is explicitely described for "description" (io.swagger.annotations v2.9.2 in my case). However the interface declaration of @RequestHeader in (spring-web.bind.annotations 5.0.12 in my case) declares #value() with an AliasFor("name") and #name() with an AliasFor("value") where setting of both at the same time results in a render error. Is this a bug or should this be reversed RequestHeader::value() should behave analog ApiParam::value() as a description field? — phirzel, Mar 09 '19 at 17:19
@Parameter(description = "description") seems to work as well — slim, May 19 '22 at 16:08

score 13 · Answer 1 · edited Nov 01 '22 at 06:08

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

I was looking for something to do on top of request header param. Unfortunately not api implicit param — Gandhi, Sep 26 '17 at 10:17
`@ApiParam(value="header description")` can be used along with `@RequestHeader` to provide header description. @DmytroBoichenko update the answer with this. — Chacko, Feb 14 '18 at 09:03
@ChackoMathew I'm sorry mate, but currently I don't have this code and can't check your solution. — Dmytro Boichenko, Feb 15 '18 at 15:59
@DmytroBoichenko I tried this way, but I can't see this value is sent as a header when I investigate the network tab of browser tools. — Supun Wijerathne, Aug 22 '18 at 07:37

score 4 · Answer 2 · answered Feb 21 '17 at 05:20

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:

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.

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

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.

Thank you for your quick response. Dont have much exposure on things you say, so will try out and get back to you. Thanks again — Gandhi, Feb 21 '17 at 05:35
Finally got time to start on this. But i m stuck at the start as i m fairly new to this. As you mentioned, i tried placing description annotation to my request header param and got an error like - "annotation type not applicable to this kind of declaration" Can you guide me in this? Also should i place the test class in your post in my spring application code? Lastly, i m not very clear about what you meant in step-4 Please advice — Gandhi, Feb 25 '17 at 09:07
When u create your annotation make sure it applies to parameters as well. Using the one that comes with spring may not work. Step 4 is simply saying make sure your plugin runs after swagger plugins. These plugins use springs Ordering for beans. — Dilip Krishnan, Mar 13 '17 at 22:19

score 0 · Answer 3 · answered Apr 02 '19 at 15:01

0

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.

answered Apr 02 '19 at 15:01

Boris

597
2
10

1

Guess that will add a new param and not update the header description – Gandhi Apr 03 '19 at 11:01
1

Yep, right you are. If the goal is only swagger, it could help. But in general case it's better to use solutions above. – Boris Apr 04 '19 at 09:45

score 0 · Answer 4 · edited Jul 16 '20 at 19:09

0

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

edited Jul 16 '20 at 19:09

David Buck

3,752
35
31
35

answered Jul 16 '20 at 18:48

hani

1

Customizing Request Header description in Swagger UI using Springfox-Swagger2

4 Answers4

Linked