@Header annotation does not parse @Schema(implementation)

[timothybasanov]

I've added something like this to my JAX-RS-based server:

 @ApiResponse(responseCode = "204",
      description = "Operation was successful",
      headers = @Header(name = Headers.EXAMPLE_HEADER,
          schema = @Schema(implementation = ExampleTypes.ExampleHeader.class))

Expected: To see this header in my openapi generated spec.
Actual: Swagger core ignored a header annotation

Additional details:

• io.swagger.v3.oas.annotations.responses.ApiResponse#headers is seemingly only read from io.swagger.v3.jaxrs2.OperationParser#getApiResponses
• It calls io.swagger.v3.core.util.AnnotationsUtils#getHeader which in turn does this:

if (header.schema() != null) {
            if (header.schema().implementation().equals(Void.class)) {
                AnnotationsUtils.getSchemaFromAnnotation(

• Looks like if schema is specified, but it has implementation, then header is silently discarded

Recommended solutions (one of):

• Ignore @Schema annotation entirely, but still add a header even if only a name is specified
• Parse "implementation" part of header spec correctly
• Throw exception when non-Void implementation is detected
• Log when non-Void implementation is detected

[ans1genie]

Any updates when this bug will be fixed? any workaround?
I would like to see this suggestion from @timothybasanov previous comment:

Parse "implementation" part of header spec correctly

[ans1genie]

A possible workaround, (it may not look clean 🤷🏻), is to implement the OperationCustomizer interface, intercept/find the header and then patch the schema programmatically.

[micryc]

Fixed by #4608