OpenAPI cookie parameter serialization

Balázs Édes 0
Viewed 21

I'm trying to implement spec-compliant parameter serialization for OpenAPI cookie parameters.

My only source for this is the docs: https://swagger.io/docs/specification/serialization/#cookie

In the description I'm seeing this line:

An optional explode keyword controls the array and object serialization

However the table below only defines array and object serialization, when explode is false.

What does this mean?:

  • Is cookie serialization with explode = true defined? If so could you please link docs?
  • If not, am I correct in saying, that explode = true basically "disables" array and object serialization, and has no effect on primitive serialization?
  • If neither of these, then what is the situation with explode?

I hope an OpenAPI expert can shed some light on this, thank you!

openapi serialization
1 Answers

Cookie serialization is defined but unfortunately not well thought out, as a result some forms of it don't make much sense. One of the specification authors admits that they "never really thought anyone would go through the trouble of describing objects in cookies in an exploded way".

In a nutshell, cookie serialization follows the same rules as query parameters with style: form.

When using explode: true:

  • A cookie parameter named param with the array value [3, 4, 5] would be sent as:

    Cookie: param=3&param=4&param=5

  • A cookie parameter named param with the object value {"foo": "test", "bar": 5} would be sent as:

    Cookie: foo=test&bar=5

    Note that the parameter name (param) is lost in this case.


As you may notice, both methods deviate from the standard Cookie header format which expects semicolon-separated name=value pairs:

Cookie: [cookie-name]=[cookie-value]; [cookie-name]=[cookie-value];...

In other words, OpenAPI's exploded form of cookies is not quite compatible with cookie parsers. For example, an OpenAPI-formatted exploded array cookie Cookie: param=3&param=4&param=5 would be parsed by a cookie parser as param = 3&param=4&param=5 - which is not what an API developer would expect.


The problems with cookie serialization are being discussed here:
Default 'explode' for cookie parameters?
Feel free to provide your implementer's feedback.

user4st0
Related