Documentation for OpenAPI's Header Object should be verbose

[shockey]

Context: I'm implementing support for examples in an OpenAPI tool.

I have a pretty good working knowledge of the Specification, but to make sure I didn't miss anything, I Cmd+F'd the 3.0.2 document for examples. and took note of which objects mention it. I missed Header Object in my list, because it only mentions that it derives itself from the Parameter Object, lacking a full documentation block that enumerates the keys that it supports.

I only noticed this because I was looking up Header Object specifically, for an unrelated task.

[handrews]

Probably a better way to solve this problem would be by looking at the schema (although it is currently in need of some help, or at least our schema publishing process is). But that's a place for explicit enumeration, while the spec is more for human readability.

[handrews]

@OAI/tsc review request: do we want to repeat things in the Header Object section or leave it as-is?

[ralfhandl]

Let's spell out explicitly which fixed fields a Header Object has, instead of requiring every reader to do the mental excercise:

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).

This already rules out half of the fixed fields of a parameter object, as our favorite allowEmptyValue already states that it only applies to query parameters 😄.

In recent Moonwalk discussions we figured out that headers and parameters are quite different beasts shaped by different boundary conditions, and these significant differences confirm our finding.

[darrelmiller]

TDC decision to add a fixed fields table to make it clear which fields a header object has. Also valuable to call out where header fields are different than parameter fields.

[handrews]

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!