Repository navigation
Documentation for OpenAPI's Header Object should be verbose #1965
Description
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.
Activity
handrews commentedon May 24, 2024
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 commentedon May 27, 2024
@OAI/tsc review request: do we want to repeat things in the Header Object section or leave it as-is?
ralfhandl commentedon May 28, 2024
Let's spell out explicitly which fixed fields a Header Object has, instead of requiring every reader to do the mental excercise:
This already rules out half of the fixed fields of a parameter object, as our favorite
allowEmptyValuealready 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 commentedon May 30, 2024
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 commentedon Jun 21, 2024
PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!