OpenAPI 3 : parameter serialization modes

[wsalembi]

OpenAPI 3 adds multiple options to serialize JSON (primitive, array, object) in header, query parameters. Which ones do we want to follow?

https://swagger.io/docs/specification/serialization/

[pvdbosch]

I guess "explode: true" shouldn't be used with spaceDelimited and pipeDelimited.
"OpenAPI spec":https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#style-examples doesn't specify this, only the swagger doc but doesn't make much sense.

The default query parameter serialization in OpenAPI 3.0 (style: form, explode:true) is the same format as we recommend for OpenAPI 2.0 in the REST guide for multi-value query params.
The data type for the query param has to specify "type: array" to allow multi-value in OpenAPI 3.0.

[pvdbosch]

My proposition...

For query params:

• use defaults (style: form, exploded: true).
  • This is compatible with our current guidelines for primitive values and arrays/multi-valued.
• perhaps recommend against using object types?
  • seems like a pain for tooling (probably don't support this form of (de)serialization) and is complex to interpret for users
  • for use cases at CBSS where querying has to be done on nested properties of the resource representation, we use individiual dot-separated query param names like "?address.street=X&address.country=Y"

For headers, in the spec style has to be simple. explode param only has an effect for object values, but I don't really see a use case and could be a pain for tooling.

For path params: simple (default normal formatting) and recommend only primitive objects (so explode has no effect) since path params are normally used as a resource id:

• If a resource is identified by multiple values, these should be in separate path segments (e.g. /blogs/5/comments/23).
• If there's a composite id for technical reasons (e.g. /images/database1-image1/), this should be presented as an abstraction to a single primitive value in the API for the user

[pvdbosch]

tested a bit with openapi-generator for spring-boot and jax-rs, but couldn't get code generation to work properly for object query parameters

  /getSomething:
    get:
      operationId: getSomething
      parameters:
        - in: query
          name: paramObject
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/RequestParamSerialized"
      responses:
        "204":
          description: OK

The generated code doesn't expand the OpenAPI object into multiple parameters; it just generates a single query param with a Java object which wouldn't work .

//Spring Boot
    ResponseEntity<Void> getSomething(
        @Parameter(name = "paramObject", description = "", in = ParameterIn.QUERY) @Valid RequestParamSerialized paramObject
    );

//jax-rs
    Response getSomething(@QueryParam("paramObject")   RequestParamSerialized paramObject);

[pvdbosch]

A feature of OpenAPI I hadn't noticed yet before: it also supports specifying a parameter using a media type:

• https://swagger.io/docs/specification/describing-parameters/
• https://spec.openapis.org/oas/v3.1.0#parameter-object

parameters:
  - in: query
    name: select
    content: # instead of schema property
      application/json:  # only single media type entry allowed; indicates how to (de)serialize (but algorithm not specified in OAS)
        schema:
          type: object
          properties:
            givenName
              type: string
            familyName:
              type: string

Haven't used it yet, so don't know how well this is supported in tooling