reuse complex spring-fox swagger annotation

Question

I am using the spring-fox2 @ApiImplicitParam annotation to make the swagger-ui show a box for including an Authorization header with a request:

@ApiImplicitParams({
        @ApiImplicitParam(
                name="Authorization",
                value="authorization header containing the bearer token",
                paramType = "header"
        )
})
public void someControllerMethod() {
    ...
}

This works fine, but I need this authorization header for each method in the controller. Copying and pasting this is code smell. Can I define some kind of shortcut annotation for this? Is there a different way of telling swagger-ui to create an input field for the authorization header?

Thanks!

score 3 · Accepted Answer · answered Apr 07 '16 at 16:00

An alternative approach to you problem is to not use annotations at all. Instead use the docket to add global operation parameters see #22. You can add headers to all the operations in your docket.

The downside to this approach might be that you might end up with multiple dockets configured such that you pre-select (see #4, #5, #6) which operations to add these parameters to.

score 1 · Answer 2 · answered Jul 24 '20 at 10:51

As an alternative solution (I was not aware of the options above), I created my own annotation that re-uses ApiImplicitParam like this:

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@RequestMapping(method = RequestMethod.GET)
@ApiImplicitParams({
    @ApiImplicitParam(dataType = "string", paramType = "header", name = HttpHeaders.AUTHORIZATION, value = Constants.ApiKey.DESC),
})
public @interface ApiGetMappingV2 {
    /**
     * Alias for {@link RequestMapping#name}.
     */
    @AliasFor(annotation = RequestMapping.class)
    String name() default "";

    /**
     * Alias for {@link RequestMapping#value}.
     */
    @AliasFor(annotation = RequestMapping.class)
    String value() default "";
}

Then I just use that annotation instead of the mapping one:

    @ApiGetMapping("/foo")
    @ApiOperation(value = "List all available foos")
    public List<Foo> all() throws MyCustomApiException {

This approach does not work for @ApiParam though, because of the targets it uses.

reuse complex spring-fox swagger annotation

2 Answers2