Parameter Serialization

For most users, their use cases are straightforward in term of parameters; however, we do have some users who have advanced use cases with parameter serialization.

OpenAPI 3.0 supports arrays and objects in operation parameters (path, query, header, and cookie) and lets you specify how these parameters should be serialized. The serialization method is defined by the style and explode keywords:

  • style defines how multiple values are delimited. Possible styles depend on the parameter location – path, query, header or cookie.

  • explode (true/false) specifies whether arrays and objects should generate separate parameters for each array item or object property.

OpenAPI serialization rules are based on a subset of URI template patterns defined by RFC 6570. Tool implementers can use existing URI template libraries to handle the serialization, as explained below.

In this tutorial, we are going to include some examples so that users can learn from them.

JSON Query Parameter

style and explode cover the most common serialization methods, but not all. For more complex scenarios (for example, a JSON-formatted object in the query string), you can use the content keyword and specify the media type that defines the serialization format. Or you can use schema to define the JSON object. For more information, please visit schema vs content. In this tutorial, we are going to create a service with one endpoint that accepts a JSON object as a query parameter. Read More »