Using Shared Headers


(Lennart) #1

I like the idea of being able to create a “Shared Header” (aka parameters with "in": "header") in Stoplight, but I can’t figure out how to link/$ref it.
We use a header as a session token, so I’d like to be able to create a Shared Header, and $ref it in both securityDefinitions and as a returned header in a Shared Response (responses).
Is this possible? And if not, where (and how) can Shared Headers be used?


(Taylor Barnett) #2

Sorry about the delay @lennart. I had to dig into this a bit.

I do not think shared parameters (including headers) can be used in securityDefinition or response objects. They CAN be used anywhere parameters are used - path parameters and request parameters. Parameters can be parameter or $ref object:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object.

While response headers cannot be a $ref object:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#response-object.


(Taylor Barnett) #3

I believe that OAS 3 made some of this better. I’d have to dig into it separately since I know they are a bit different.


(Lennart) #4

Thanks for the reply @taylor.
It looks like OAS 3 does support this: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#response-object
I’m very much looking forward to Design support for OAS3 :slight_smile:


(Taylor Barnett) #5

No problem. We can’t wait either. I’ve been editing mine in Code view and it reminded me how not fun that is.