Skip to main content

Introducing support for complex query params in TypeScript

· 2 min read

TypeScript SDKs now support complex query parameters that allow you to send complex types and arrays/maps of complex types in query strings.

Details​

OpenAPI specification allows sending any kind of payload as a query parameter. The following example shows how to set the required type for any query parameter.

"parameters": [
   {
     "name": "petId",
     "in": "query",
     "description": "ID of pet that needs to be updated",
     "required": true,
     "schema": {
       "type": "string"
     }
   }
]

This payload could either be of a simple type i.e string, boolean, number, or could be a complex type i.e model, array, or map. Previously, TypeScript SDKs only supported simple types along with array/map of simple types but did not support complex types, array/map of complex types in the query string.

What has changed?​

We are now introducing the support for complex query parameters. Now, TypeScript SDKs have the ability to send a complex type as well as arrays/maps of complex types in query strings. For example, take the following model named Pet:

export interface Pet{
  petId: number;
  petName: string;
  siblings: string[];
}
const Cat: Pet= {
  petId: 345,
  petName: 'PersianCat',
  Siblings: [‘catA’, ‘catB’, ‘catC’]
};

This model can now be sent in a query string, and the resultant decoded query string would look like this:

/sendPet?pet[petId]=345&pet[petName]=PersianCat&pet[siblings][0]=catA&pet[siblings][1]=catB&pet[siblings][2]=catC

We also added the support for different array serialization formats that would apply to arrays of simple types that may appear within a model. In the above example of model Pet, the field siblings is an array of simple type i.e. string, and is being serialized by Indexed array serialization.

Along with this, support for other array serialization formats like Plain, UnIndexed, CommaSeparated, TabSeparated, PipeSeperated has also been added. The default format is Indexed but you can set any of these formats in an OAS like:

{
 "openapi": "3.0.0",
 "info": {
   "x-codegen-settings": {
       "ArraySerialization": "Plain"
   }
 }

Let's take the same model and try applying other array serialization formats.

Plain Array Serialization​

/sendPet?pet[petId]=345&pet[petName]=PersianCat&pet[siblings]=catA&pet[siblings]=catB&pet[siblings]=catC

UnIndexed Array Serialization​

/sendPet?pet[petId]=345&pet[petName]=PersianCat&pet[siblings][]=catA&pet[siblings][]=catB&pet[siblings][]=catC

CommaSeparated Array Serialization​

/sendPet?pet[petId]=345&pet[petName]=PersianCat&pet[siblings]=catA,catB,catC

TabSeparated Array Serialization​

/sendPet?pet[petId]=345&pet[petName]=PersianCat&pet[siblings]=catA\tcatB\tcatC

PipeSeparated Array Serialization​

/sendPet?pet[petId]=345&pet[petName]=PersianCat&pet[siblings]=catA|catB|catC