Header annotation doesn't fully support OAS 3.0

[christophejan]

Currently, all 3.x.x versions of OpenAPI Specification define Header object as :

The Header Object follows the structure of the Parameter Object with the following changes:

1. name MUST NOT be specified, it is given in the corresponding headers map.
2. in MUST NOT be specified, it is implicitly in header.
3. All traits that are affected by the location MUST be applicable to a location of header (for example, style).

But current swagger-core Header annotation seems to have a lot of missing attributes when I compare it to Parameter annotation :

• allowEmptyValue
• style
• explode
• allowReserved
• array
• content

I think all the matching Parameter object fields can't be defined currently on response header through swagger annotations, but should.

[christophejan]

• Note that bringing Header annotation and it's processing closer to the Parameter annotation could solve #2965

[micryc]

Due to openapi spec there is no reason to add most of mentioned fields:

allowEmptyValue – valid only for query parameters

style – ‘header’ style is always set to simple, we don’t need that annotation then

allowReserved – this property only applies to parameters with “in” value of “query”, so it’s also not applicable as it’s header

We decided to take a deeper look on other missing fields like: explode, array, hidden, example, examples.

These were added by https://github.com/swagger-api/swagger-core/pull/4608