Openapi-specification: Multiple 'Set-Cookie' headers in one response

[JohnnyNiu]

Is it possible to have multiple 'Set-Cookie' headers in one response? As is known there are two ways to set cookies header in the response:
- Having separated headers
- Folding into 1 header and using comma separated

The later way however is deprecated in (RFC6265)[http://www.rfc-editor.org/rfc/rfc6265.txt] and not supported by some latest browsers.

   Origin servers SHOULD NOT fold multiple Set-Cookie header fields into
   a single header field.  The usual mechanism for folding HTTP headers
   fields (i.e., as defined in [RFC2616]) might change the semantics of
   the Set-Cookie header field because the %x2C (",") character is used
   by Set-Cookie in a way that conflicts with such folding.

So that below can be valid:

responses:
   200:
   description: "Response with content"
   headers:
       Set-Cookie:
           type: String
           description: "eg. key1=value1"
       Set-Cookie:
           type: String
           description: "eg. key2=value2"

[ePaul]

You can of course have multiple headers with the same name in your HTTP response, but it looks like OpenAPI 2.0 has no way of documenting that. The way shown by you doesn't work (a JSON or YAML object can have each key just once, and if you repeat one, most parsers will retain just one of them).

I think it looks like the same with the current RC of OpenAPI 3.0 – while the handling of plural parameters changed (via style instead of collectionFormat), I didn't find anything for "multiple headers of the same name". (I guess that could be handled by adding a new style value here.)

(By the way, I think that Cookies should not be necessary in a Restful API – but the same applies to other headers too.)

[RobDolinMS]

Per @darrelmiller - We have a way to capture this in the request but not in the response.

@JohnnyNiu Is that sufficient for your use case?

[honzajavorek]

The Set-Cookie header is typically a response header.

[jwalton]

@RobDolinMS Also, you can't have multiple cookie headers in the request. As per RFC 6265 S5.4:

When the user agent generates an HTTP request, the user agent MUST NOT attach more than one Cookie header field.

[mikejav]

I got rid of this problem with this one simple trick:

just surround the next same header by quotation marks and add null char at the beginning.

headers:
  Set-Cookie:
    description: Session cookie
    schema:
      type: string
      example: SESSIONID=abcde12345; Path=/
  "\0Set-Cookie":
    description: CSRF token
    schema:
      type: string
      example: CSRFTOKEN=fghijk678910; Path=/; HttpOnly

result:

[dfornika]

I'm interested in this issue for the purpose of using the Link header for web linking. There's an example in the RFC that shows multiple links being serialized either in a single Link header or multiple headers. It seems like it would be simpler to parse the links if they were in separate headers.

[njr-11]

I found this issue when looking for a way to represent the ability to have multiple occurrences of the same header. In my case, the number of occurrences is unknown, and so using an array seemed ideal. It almost works, except that explode: true doesn't appear to be working,

    My-Header-Example:
      name: My-Header-Example
      in: header
      description: "Useful description goes here"
      schema:
        type: array
        items:
          type: string
      explode: true

I was expecting it to generate multiple header entries like this,

-H  "My-Header-Example: headerItem1" -H  "My-Header-Example: headerItem2" ...

But instead ends up with a comma-delimited list within a single field,

-H  "My-Header-Example: headerItem1,headerItem2" ...

Would it be possible to fix so that explode: true is honored for header? That might be one way of addressing concerns that others have raised, although they would need to comment on that themselves because you would end up with just a single description field for all of the entries, which in my case is exactly what I want, but might or might not be adequate in the other scenarios documented here.

[darrelmiller]

@njr-11 How this headers are actually rendered is a function of the tool you are using, not the specification. I would suggest bringing this up with whatever tooling you are using. On the other hand, for HTTP headers that allow duplicate headers, the two forms you show are considered semantically equivalent. See https://tools.ietf.org/html/rfc7230#section-3.2.2