Share header with multiple response objects

[huangsam]

Can there not just be a simple header generically at the response level not specific to each of the status codes? For our case, this kind of header is 99% the same across our codebase.

---

responses:
  200:
    description: no error
    headers:
      Content-Type:
        description: application/json
        type: string

It would be a pain to copy+paste this to each and every routine that supports HTTP JSON responses.

[webron]

Unfortunately, no. The headers in the responses is actually a new feature in 2.0, and we hadn't thought of the option to allow a global definition for it.

[RobDolinMS]

@webron Given your response above, should we close this issue? /cc @huangsam

[webron]

It's still an option we might consider in future versions.

[whitlockjc]

Isn't this handled in 3.0 You define your reusable headers at #/components/headers and then use a $ref to reuse it. It won't allow you to have a singular reference to define all common headers in a response but then you could probably use #/components/responses for that.

[webron]

Yeah, but this is not about reusability (which makes it easier) - it's about declaring it only once for all.

[darrelmiller]

What happens when someone declares a Content-Type header for all responses and then adds a 204 response?

[webron]

@darrelmiller did we not just talk today about disallowing Content-Type headers? :)

[darrelmiller]

@webron Fine: content-length, Transfer-encoding, Range, ... how obscure do I need to get? :-)

[michael-o]

Obviously the example is bad. consider the following model:

paths:
  /api/v1/modules:
    get:
      tags:
        - Modules
      summary: Lists all available modules
      operationId: listModules
      responses:
        200:
          $ref: "#/components/responses/modulesOk"
        400:
          $ref: "#/components/responses/400"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        404:
          $ref: "#/components/responses/404"
        406:
          $ref: "#/components/responses/406"
        408:
          $ref: "#/components/responses/408"
        500:
          $ref: "#/components/responses/500"

Codes like 401, 403, 404, 406, 408 will repeat through all paths. If one could add this to a generic section and selectively overwrite it, it'd be great. Having 50 paths and adding that block over and over again ist just pain.

[guptaashwanee]

Is this still not available in the schemas? This will be the great feature and I was also looking for this for a long time.

[msolujic]

let use this discussion to underline two common issues and possible enhancements regarding response headers:

1. having a way to define common response headers for some API once and override only some of them if needed
2. we miss the ability to include multiple headers in one $ref, and not being forced to have 8 refs for 8 headers each and every time

is this planned for some future OAS spec?