Query parameter serialization for objects is not the openapi default

[acerola1]

Description

When serializing query parameters for objects using the library, the serialization method employed does not match the OpenAPI 3.0 specification's default behavior. Specifically, the library uses a "deepObject" serialization style instead of the expected "form" serialization with explode=true, leading to an incorrect query parameter format.
Openapi spec

Reproduction
Calling the:

const {
  data, // only present if 2XX response
  error, // only present if 4XX or 5XX response
} = await GET("/user", {
  params: {
    path: {id: {role: "admin", firstName: "Alex"}},
  },
});

the url parameters are: "id[role]=admin&id[firstName]=Alex"

Expected result

the url parameters should be: "role=admin&firstName=Alex"

Checklist

• I’m willing to open a PR (see CONTRIBUTING.md)

[drwpow]

You are right the docs are incorrect and says the default is form/explode when it’s deepObject. The docs should be fixed, but I’m unsure if the default should be changed again, because there were many issues opened about simpler serializers being used.

No matter what the default is, there will always be a large number of users whose backends implement a different style. In that vein, would it be worthwhile to ship some additional querySerializers that handle alternate syntaxes? Perhaps something like:

import createClient from 'openapi-fetch';
import { formExplode } from 'openapi/serializers';

createClient({
  querySerializer: formExplode
});

[acerola1]

Yes it is not easy. Maybe it should be more finer grained. Array and object serialization can be different. I created a serializer for formExplode for object. It may help someone.

const serializePrimitive = (key, value) => `${key}=${encodeURIComponent(String(value))}`;

const serializeArray = (key, value, serializer) => {
  if (!value.length) return undefined;
  return value
    .map((item) => serializer(key, item))
    .filter(Boolean)
    .join('&');
};

const serializeObject = (value, serializer) => {
  const entries = Object.entries(value).filter(([_, v]) => v !== undefined && v !== null);
  if (!entries.length) return undefined;
  return entries
    .map(([k, v]) => serializer(k, v))
    .filter(Boolean)
    .join('&');
};

const queryParamSerializer = (key, value) => {
  if (value === null || value === undefined) return undefined;

  const type = typeof value;
  if (type === 'string' || type === 'number' || type === 'boolean') return serializePrimitive(key, value);
  if (Array.isArray(value)) return serializeArray(key, value, queryParamSerializer);
  if (type === 'object') return serializeObject(value, queryParamSerializer);

  return undefined;
};

export const querySerializer = (q) => {
  const search: string[] = [];
  if (q && typeof q === 'object') {
    for (const [k, v] of Object.entries(q)) {
      const value = queryParamSerializer(k, v);
      if (value) {
        search.push(value);
      }
    }
  }
  return search.join('&');
};

[drwpow]

I really like the idea of separating object + array serialization! I don’t think anyone’s suggested that before. Adding that would make it easier for people to customize their own serializers for sure, and that could be added in a backwards-compatible way.

[drwpow]

Also digging into this, I realize that we don’t support path serialization very well either, but should. Will add a minor breaking change to the library to handle this (and provide for easier overrides).

Since this is a breaking change, this will probably be released in 0.9.0 along with #1521.