Skip to content

Commit 9002418

Browse files
luxassluxass
authored
feat(openapi-fetch): add support for pathSerializer option (#2362)
* feat(openapi-fetch): add support for pathSerializer option - Introduced `pathSerializer` to `ClientOptions` for enhanced path handling. - Updated `createClient` function to utilize `pathSerializer` from options. - Modified `createFinalURL` to apply the provided `pathSerializer`. * test: add pathSerializer tests for custom serialization * chore: add changeset * docs: update openapi-fetch docs * chore: fix link * chore: actually fix link
1 parent ed0c26c commit 9002418

File tree

5 files changed

+149
-4
lines changed

5 files changed

+149
-4
lines changed

‎.changeset/late-moments-build.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"openapi-fetch": minor
3+
---
4+
5+
Added support for setting a custom path serializers either globally or per request. This allows you to customize how path parameters are serialized in the URL. E.g. you can use a custom serializer to prevent encoding of a path parameter, if you need to pass a value that should not be encoded.

‎docs/openapi-fetch/api.md‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ createClient<paths>(options);
1919
| `fetch` | `fetch` | Fetch instance used for requests (default: `globalThis.fetch`) |
2020
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
2121
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
22+
| `pathSerializer` | PathSerializer | (optional) Provide a [pathSerializer](#pathserializer) |
2223
| (Fetch options) | | Any valid fetch option (`headers`, `mode`, `cache`, `signal` …) ([docs](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options) |
2324

2425
## Fetch options
@@ -35,8 +36,9 @@ client.GET("/my-url", options);
3536
| `body` | `{ [name]:value }` | [requestBody](https://spec.openapis.org/oas/latest.html#request-body-object) data for the endpoint |
3637
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
3738
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
39+
| `pathSerializer` | PathSerializer | (optional) Provide a [pathSerializer](#pathserializer) |
3840
| `parseAs` | `"json"` \| `"text"` \| `"arrayBuffer"` \| `"blob"` \| `"stream"` | (optional) Parse the response using [a built-in instance method](https://developer.mozilla.org/en-US/docs/Web/API/Response#instance_methods) (default: `"json"`). `"stream"` skips parsing altogether and returns the raw stream. |
39-
| `baseUrl` | `string` | Prefix the fetch URL with this option (e.g. `"https://myapi.dev/v1/"`) |
41+
| `baseUrl` | `string` | Prefix the fetch URL with this option (e.g. `"https://myapi.dev/v1/"`) |
4042
| `fetch` | `fetch` | Fetch instance used for requests (default: fetch from `createClient`) |
4143
| `middleware` | `Middleware[]` | [See docs](/openapi-fetch/middleware-auth) |
4244
| (Fetch options) | | Any valid fetch option (`headers`, `mode`, `cache`, `signal`, …) ([docs](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options)) |
@@ -208,7 +210,33 @@ const { data, error } = await client.POST("/tokens", {
208210
});
209211
```
210212

211-
## Path serialization
213+
## pathSerializer
214+
215+
Similar to [querySerializer](#queryserializer) and [bodySerializer](#bodyserializer), `pathSerializer` allows you to customize how path parameters are serialized. This is useful when your API uses a non-standard path serialization format, or you want to change the default behavior.
216+
217+
### Custom Path Serializer
218+
219+
You can provide a custom path serializer when creating the client:
220+
221+
```ts
222+
const client = createClient({
223+
pathSerializer(pathname, pathParams) {
224+
let result = pathname;
225+
for (const [key, value] of Object.entries(pathParams)) {
226+
result = result.replace(`{${key}}`, `[${value}]`);
227+
}
228+
return result;
229+
},
230+
});
231+
232+
const { data, error } = await client.GET("/users/{id}", {
233+
params: { path: { id: 5 } },
234+
});
235+
236+
// URL: `/users/[5]`
237+
```
238+
239+
### Default Path Serializer
212240

213241
openapi-fetch supports path serialization as [outlined in the 3.1 spec](https://swagger.io/docs/specification/serialization/#path). This happens automatically, based on the specific format in your OpenAPI schema:
214242

‎packages/openapi-fetch/src/index.d.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ export interface ClientOptions extends Omit<RequestInit, "headers"> {
2323
querySerializer?: QuerySerializer<unknown> | QuerySerializerOptions;
2424
/** global bodySerializer */
2525
bodySerializer?: BodySerializer<unknown>;
26+
/** global pathSerializer */
27+
pathSerializer?: PathSerializer;
2628
headers?: HeadersOptions;
2729
/** RequestInit extension object to pass as 2nd argument to fetch when supported (defaults to undefined) */
2830
requestInitExt?: Record<string, unknown>;
@@ -64,6 +66,8 @@ export type QuerySerializerOptions = {
6466

6567
export type BodySerializer<T> = (body: OperationRequestBodyContent<T>) => any;
6668

69+
export type PathSerializer = (pathname: string, pathParams: Record<string, unknown>) => string;
70+
6771
type BodyType<T = unknown> = {
6872
json: T;
6973
text: Awaited<ReturnType<Response["text"]>>;
@@ -118,6 +122,7 @@ export type RequestOptions<T> = ParamsOption<T> &
118122
baseUrl?: string;
119123
querySerializer?: QuerySerializer<T> | QuerySerializerOptions;
120124
bodySerializer?: BodySerializer<T>;
125+
pathSerializer?: PathSerializer;
121126
parseAs?: ParseAs;
122127
fetch?: ClientOptions["fetch"];
123128
headers?: HeadersOptions;
@@ -129,6 +134,7 @@ export type MergedOptions<T = unknown> = {
129134
parseAs: ParseAs;
130135
querySerializer: QuerySerializer<T>;
131136
bodySerializer: BodySerializer<T>;
137+
pathSerializer: PathSerializer;
132138
fetch: typeof globalThis.fetch;
133139
};
134140

@@ -324,6 +330,7 @@ export declare function createFinalURL<O>(
324330
path?: Record<string, unknown>;
325331
};
326332
querySerializer: QuerySerializer<O>;
333+
pathSerializer: PathSerializer;
327334
},
328335
): string;
329336

‎packages/openapi-fetch/src/index.js‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ export default function createClient(clientOptions) {
2828
fetch: baseFetch = globalThis.fetch,
2929
querySerializer: globalQuerySerializer,
3030
bodySerializer: globalBodySerializer,
31+
pathSerializer: globalPathSerializer,
3132
headers: baseHeaders,
3233
requestInitExt = undefined,
3334
...baseOptions
@@ -51,6 +52,7 @@ export default function createClient(clientOptions) {
5152
parseAs = "json",
5253
querySerializer: requestQuerySerializer,
5354
bodySerializer = globalBodySerializer ?? defaultBodySerializer,
55+
pathSerializer: requestPathSerializer,
5456
body,
5557
middleware: requestMiddlewares = [],
5658
...init
@@ -74,6 +76,8 @@ export default function createClient(clientOptions) {
7476
});
7577
}
7678

79+
const pathSerializer = requestPathSerializer || globalPathSerializer || defaultPathSerializer;
80+
7781
const serializedBody =
7882
body === undefined
7983
? undefined
@@ -114,7 +118,7 @@ export default function createClient(clientOptions) {
114118
let id;
115119
let options;
116120
let request = new Request(
117-
createFinalURL(schemaPath, { baseUrl: finalBaseUrl, params, querySerializer }),
121+
createFinalURL(schemaPath, { baseUrl: finalBaseUrl, params, querySerializer, pathSerializer }),
118122
requestInit,
119123
);
120124
let response;
@@ -136,6 +140,7 @@ export default function createClient(clientOptions) {
136140
parseAs,
137141
querySerializer,
138142
bodySerializer,
143+
pathSerializer,
139144
});
140145
for (const m of finalMiddlewares) {
141146
if (m && typeof m === "object" && typeof m.onRequest === "function") {
@@ -630,7 +635,7 @@ export function defaultBodySerializer(body, headers) {
630635
export function createFinalURL(pathname, options) {
631636
let finalURL = `${options.baseUrl}${pathname}`;
632637
if (options.params?.path) {
633-
finalURL = defaultPathSerializer(finalURL, options.params.path);
638+
finalURL = options.pathSerializer(finalURL, options.params.path);
634639
}
635640
let search = options.querySerializer(options.params.query ?? {});
636641
if (search.startsWith("?")) {

‎packages/openapi-fetch/test/common/params.test.ts‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,106 @@ describe("params", () => {
191191
// expect post_id to be encoded properly
192192
expect(actualPathname).toBe("/path-params/%F0%9F%A5%B4");
193193
});
194+
195+
describe("pathSerializer", () => {
196+
test("global", async () => {
197+
let actualPathname = "";
198+
const client = createObservedClient<paths>(
199+
{
200+
pathSerializer: (pathname, pathParams) => {
201+
// Custom serializer that wraps path values in brackets
202+
let result = pathname;
203+
for (const [key, value] of Object.entries(pathParams)) {
204+
result = result.replace(`{${key}}`, `[${value}]`);
205+
}
206+
return result;
207+
},
208+
},
209+
async (req) => {
210+
actualPathname = new URL(req.url).pathname;
211+
return Response.json({});
212+
},
213+
);
214+
215+
await client.GET("/resources/{id}", {
216+
params: {
217+
path: { id: 123 },
218+
},
219+
});
220+
221+
expect(actualPathname).toBe("/resources/[123]");
222+
});
223+
224+
test("per-request", async () => {
225+
let actualPathname = "";
226+
const client = createObservedClient<paths>(
227+
{
228+
pathSerializer: (pathname, pathParams) => {
229+
// Default global serializer (should be overridden)
230+
let result = pathname;
231+
for (const [key, value] of Object.entries(pathParams)) {
232+
result = result.replace(`{${key}}`, `global-${value}`);
233+
}
234+
return result;
235+
},
236+
},
237+
async (req) => {
238+
actualPathname = new URL(req.url).pathname;
239+
return Response.json({});
240+
},
241+
);
242+
243+
await client.GET("/resources/{id}", {
244+
params: {
245+
path: { id: 456 },
246+
},
247+
pathSerializer: (pathname, pathParams) => {
248+
// Per-request serializer should override global
249+
let result = pathname;
250+
for (const [key, value] of Object.entries(pathParams)) {
251+
result = result.replace(`{${key}}`, `request-${value}`);
252+
}
253+
return result;
254+
},
255+
});
256+
257+
expect(actualPathname).toBe("/resources/request-456");
258+
});
259+
260+
test("complex path params with custom serializer", async () => {
261+
let actualPathname = "";
262+
const client = createObservedClient<paths>(
263+
{
264+
pathSerializer: (pathname, pathParams) => {
265+
// Custom serializer that handles different value types
266+
let result = pathname;
267+
for (const [key, value] of Object.entries(pathParams)) {
268+
if (typeof value === "string") {
269+
result = result.replace(`{${key}}`, `custom:${value}`);
270+
} else {
271+
result = result.replace(`{${key}}`, `other:${value}`);
272+
}
273+
}
274+
return result;
275+
},
276+
},
277+
async (req) => {
278+
actualPathname = new URL(req.url).pathname;
279+
return Response.json({});
280+
},
281+
);
282+
283+
await client.GET("/path-params/{string}", {
284+
params: {
285+
path: {
286+
string: "test-value",
287+
},
288+
},
289+
});
290+
291+
expect(actualPathname).toBe("/path-params/custom:test-value");
292+
});
293+
});
194294
});
195295

196296
describe("header", () => {

0 commit comments

Comments
 (0)