Header and Parameter in header ambiguity

[pmerson]

The Components object has:

• parameters - collection of Parameter objects
• headers - collection of Header objects

However, a Parameter can be a header (when in == "header").
This inherent ambiguity creates confusion when one tries to create a global/group customization.

Can the ambiguity be removed (maybe deprecating the Header object or the "header" location of Parameter)?
If not, when should I declare a header as a Parameter and when should I declare it as a Header? The answer to this last question is direly needed in the documentation.

[webron]

The Header Object is used in responses when describing what headers can be returned as part of it (it's also used in the Encoding Object but that's not common). The Specification mentions all the places where you can use the Header Object.

[pmerson]

@webron Thanks for the answer. If I understand correctly, you're saying the Header object is for specifying headers in HTTP response messages.

I think many people like me are trying to create customizations of Open API using Spring Doc. Spring Doc has this link to the Open API Spec that describes Components, where there's a link to the Header object. In none of these linked pieces of documentation I see the information that the Header object is for headers in the HTTP response.

It would be great if the documentation of Components.headers and Header could make that information explicit.

[handrews]

Suggestions for Spring Doc should be directed to its maintainers. Since the spec question has been answered, I'm closing this.