Question: How to define reusable headers that can be used in both request and response

[vnalla]

How to define reusable headers that can be used in both request and response?
if a headers is defined in components.parameters it is not allowing to use in response.headers and vice-versa. What if an header that will present in both request and response? do I have to define it twice in component.parameters and component.headers?

thanks

[r-sreesaran]

As of now it needs to be defined twice. Because in case of Request it is considered as parameter, in case of response it needs to be defined as the header. https://swagger.io/docs/specification/components/. But providing an option to re use this will help us avoid DRY.

[kscheirer]

I will take a look at if/how overlays can solve this problem as part of determining whether overlay spec is sufficient.

Possibly this could be solved with OpenAPI's components.headers - but request parameters and response headers have slightly different formats.

Strictly on how overlays might solve this problem, I think the example below would work. It's 2 actions to account for the aforementioned difference. What do you think?

{
  "overlay": "1.0.0",
  "info": {
    "title": "Common Headers Overlay",
    "version": "1.0.0"
  },
  "actions": [
    {
      "target": "info",
      "update": {
        "x-overlay-applied": "common-headers"
      }
    },
    {
      "description": "Add request header",
      "target": "paths[*].get.parameters",
      "update": {
        "name": "request-id",
        "in": "header",
        "description": "API consumers send this header with a unique ID identifying the request header for tracking purpose, sent header back as a response header",
        "schema": {
          "type": "string"
        }
      }
    },
    {
      "description": "Add response header",
      "target": "paths[*].get.responses[*].headers",
      "update": {
        "request-id": {
          "description": "API consumers send this header with a unique ID identifying the request header for tracking purpose, sent header back as a response header",
          "schema": {
            "type": "string"
          }
        }
      }
    }
  ]
}

[martinsirbe]

As we must specify the in property with header as its value when defining a reusable header schema that can be listed under parameters for an operation, how about modifying the in property to enable differentiation between request_header and response_header? The only issue that then arises is how to handle situations where the response headers vary based on the HTTP status code. I'd love to hear your thoughts on this.

[handrews]

I don't think there's any way to do this before 4.0 as it would require a breaking change and is related to the broader objects vs arrays discussion (OAI/sig-moonwalk#32).