Cookie Parameters in OpenAPI

Cookie parameters are serialized at runtime to an HTTP cookie header. Types are generally serialized to a string representation, and only form style is available.

Currently, cookies are not well supported by OpenAPI and this may change in the future, so using the default style: form and explode: true values results in serialization incompatible with most cookie parsers.

Therefore, it is recommended to only use cookies for primitive types or arrays with explode: false, but the current serialization behaviors are included below for completeness.

If using cookies for authentication, it is recommended to use the OpenAPI security field to document a security scheme instead of a cookie parameter.

Primitive Types As Cookies in OpenAPI

Primitive types such as string, number, integer, and boolean are serialized as a string.

For the example below, we will use a cookie parameter named drink-limit with a value of 5.

Style	Explode == `true`	Explode == `false`
`form`	`Cookie: drink-limit=5` (default)	`Cookie: drink-limit=5`

Simple Arrays As Cookies in OpenAPI

For simple arrays of primitive types such as string, number, integer, and boolean, serialization will vary depending on the explode field.

For the example below, we will use a cookie parameter named drink-types with a value of ["gin", "vodka", "rum"].

Style	Explode == `true`	Explode == `false`
`form`	`Cookie: drink-types=gin&drink-types=vodka&drink-types=rum` (default)	`Cookie: drink-types=gin,vodka,rum`

Simple Objects As Cookies in OpenAPI

For simple objects whose fields are primitive types such as string, number, integer, and boolean, serialization will vary depending on the explode field.

For the example below, we will use a cookie parameter named drink-filter with a value of {"type": "cocktail", "strength": 5}.

Style	Explode == `true`	Explode == `false`
`form`	`Cookie: type=cocktail&strength=5` (default)	`Cookie: drink-filter=type,cocktail,strength,5`

Complex Objects and Arrays As Cookies in OpenAPI

For complex objects and arrays, serialization in a cookie parameter is only really possible using content and not any style options.

For example, to serialize using JSON, the following:

parameters:
  - name: drink-filter
    in: cookie
    content:
      application/json:
        schema:
          type: object
          properties:
            type:
              type: array
              items:
                type: string
            strength:
              type: array
              items:
                type: integer

Would serialize to Cookie: drink-filter={"type":["cocktail","mocktail"],"strength":[5,10]}.