prescottprue/openapi-fetch

openapi-fetch

Comprehensive guide for openapi-fetch — a type-safe fetch client that uses OpenAPI schemas for zero-overhead type checking at build time.

When to Apply

Reference these guidelines when:

• Creating API clients from OpenAPI schemas
• Making type-safe HTTP requests (GET, POST, PUT, DELETE, PATCH, etc.)
• Implementing middleware for auth, logging, caching, or error handling
• Configuring query/body/path serialization
• Testing API clients with mocks
• Integrating with React, Vue, Svelte, Next.js, or Nuxt

Installation

npm i openapi-fetch
npm i -D openapi-typescript typescript

Schema Generation

Generate TypeScript types from your OpenAPI schema:

npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts

This produces a paths type export used to type the client.

Recommended: Enable noUncheckedIndexedAccess in tsconfig.json for enhanced type safety.

Creating a Client

import createClient from "openapi-fetch";
import type { paths } from "./my-openapi-3-schema";

const client = createClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});

createClient Options

| Option | Type | Description | |--------|------|-------------| | baseUrl | string | Prefix all fetch URLs | | fetch | (input: Request) => Promise<Response> | Custom fetch instance (default: globalThis.fetch) | | Request | typeof Request | Custom Request constructor | | querySerializer | QuerySerializer \| QuerySerializerOptions | Global query param serializer | | bodySerializer | BodySerializer | Global body serializer | | pathSerializer | PathSerializer | Global path param serializer | | headers | HeadersOptions | Default headers for all requests | | requestInitExt | Record<string, unknown> | Extension object passed as 2nd argument to fetch | | (any fetch option) | | Any valid RequestInit option (mode, cache, credentials, signal, etc.) |

Making Requests

All HTTP methods are available: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD, TRACE.

// GET request
const { data, error, response } = await client.GET("/blogposts/{post_id}", {
  params: {
    path: { post_id: "123" },
    query: { format: "json" },
  },
});

// POST request
const { data, error } = await client.POST("/blogposts", {
  body: {
    title: "My Post",
    content: "Hello world",
  },
});

// PUT request
const { data, error } = await client.PUT("/blogposts/{post_id}", {
  params: { path: { post_id: "123" } },
  body: { title: "Updated Title" },
});

// DELETE request
const { data, error } = await client.DELETE("/blogposts/{post_id}", {
  params: { path: { post_id: "123" } },
});

Response Structure

Every method returns an object with:

• data — Present only on 2xx responses. Typed from the schema's success response.
• error — Present only on 4xx/5xx responses. Typed from the schema's error response.
• response — The raw Response object with status, headers, etc.

data and error are mutually exclusive — check one to narrow the type:

const { data, error } = await client.GET("/blogposts/{post_id}", {
  params: { path: { post_id: "123" } },
});

if (error) {
  // error is typed, data is undefined
  console.error(error);
  return;
}
// data is typed, error is undefined
console.log(data.title);

Fetch Options Per Request

| Option | Type | Description | |--------|------|-------------| | params | { path?, query?, header?, cookie? } | Path, query, header, and cookie parameters | | body | object | Request body (typed from schema) | | parseAs | "json" \| "text" \| "arrayBuffer" \| "blob" \| "stream" | Response parsing method (default: "json") | | querySerializer | QuerySerializer \| QuerySerializerOptions | Per-request query serializer | | bodySerializer | BodySerializer | Per-request body serializer | | pathSerializer | PathSerializer | Per-request path serializer | | baseUrl | string | Override base URL for this request | | fetch | fetch | Override fetch for this request | | headers | HeadersOptions | Per-request headers (merged with client defaults) | | middleware | Middleware[] | Per-request middleware | | (any fetch option) | | Any valid RequestInit option |

Generic request Method

For dynamic HTTP methods:

const { data, error } = await client.request("GET", "/blogposts/{post_id}", {
  params: { path: { post_id: "123" } },
});

parseAs Option

Control how the response body is parsed:

// Get response as text
const { data } = await client.GET("/file", { parseAs: "text" });

// Get response as blob
const { data } = await client.GET("/image", { parseAs: "blob" });

// Get response as stream
const { data } = await client.GET("/large-file", { parseAs: "stream" });

// Get response as arrayBuffer
const { data } = await client.GET("/binary", { parseAs: "arrayBuffer" });

Middleware

Middleware intercepts requests and responses for all fetches. Use for auth, logging, caching, error handling, etc.

Middleware Interface

import type { Middleware } from "openapi-fetch";

const myMiddleware: Middleware = {
  async onRequest({ request, schemaPath, params, id, options }) {
    // Modify or return a new Request
    // Return a Response to short-circuit (skip fetch + remaining onRequest handlers)
    // Return undefined to skip this middleware
    return request;
  },
  async onResponse({ request, response, schemaPath, params, id, options }) {
    // Modify or return a new Response
    // Return undefined to skip
    return response;
  },
  async onError({ request, error, schemaPath, params, id, options }) {
    // Return nothing: logs without re-throwing
    // Return an Error: throws the modified error
    // Return a Response: treats the request as successful
  },
};

Callback Parameters

| Name | Type | Available in | Description | |------|------|-------------|-------------| | request | Request | all | Current Request object | | response | Response | onResponse | Response from endpoint | | error | unknown | onError | Error thrown by fetch | | schemaPath | string | all | Original OpenAPI path (e.g., "/blogposts/{post_id}") | | params | object | all | Original params object (query, header, path, cookie) | | id | string | all | Unique ID for this request | | options | MergedOptions | all | Read-only client options |

Registering and Ejecting

client.use(myMiddleware);       // Register
client.use(mw1, mw2, mw3);     // Register multiple
client.eject(myMiddleware);     // Unregister

Execution Order

• onRequest handlers run in registration order
• onResponse handlers run in reverse order

Auth Middleware Pattern

import type { Middleware } from "openapi-fetch";

let accessToken: string | undefined = undefined;

const authMiddleware: Middleware = {
  async onRequest({ request }) {
    if (!accessToken) {
      const authRes = await someAuthFunc();
      accessToken = authRes.accessToken;
    }
    request.headers.set("Authorization", `Bearer ${accessToken}`);
    return request;
  },
};

client.use(authMiddleware);

Conditional Middleware (Skip Certain Routes)

const UNPROTECTED_ROUTES = ["/v1/login", "/v1/logout", "/v1/public/"];

const authMiddleware: Middleware = {
  onRequest({ schemaPath, request }) {
    if (UNPROTECTED_ROUTES.some((path) => schemaPath.startsWith(path))) {
      return undefined; // Skip this middleware
    }
    request.headers.set("Authorization", `Bearer ${accessToken}`);
    return request;
  },
};

Caching Middleware Pattern

const cache = new Map<string, Response>();
const getCacheKey = (request: Request) => `${request.method}:${request.url}`;

const cacheMiddleware: Middleware = {
  onRequest({ request }) {
    const cached = cache.get(getCacheKey(request));
    if (cached) {
      return cached.clone(); // Return Response to short-circuit
    }
  },
  onResponse({ request, response }) {
    if (response.ok) {
      cache.set(getCacheKey(request), response.clone());
    }
  },
};

Error-Throwing Middleware

By default, openapi-fetch does not throw on 4xx/5xx — it returns { error }. To throw instead:

const throwOnError: Middleware = {
  onResponse({ response }) {
    if (!response.ok) {
      throw new Error(`${response.url}: ${response.status} ${response.statusText}`);
    }
  },
};

Body Statefulness

Request/Response bodies are stateful (can only be read once). When reading without modification, clone first:

const loggingMiddleware: Middleware = {
  async onResponse({ response }) {
    const data = await response.clone().json(); // Clone before reading
    console.log(data);
    return undefined; // Don't modify
  },
};

Query Serialization

Object Configuration

const client = createClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
  querySerializer: {
    array: {
      style: "pipeDelimited", // "form" (default) | "spaceDelimited" | "pipeDelimited"
      explode: false,         // default: true
    },
    object: {
      style: "form",          // "form" | "deepObject" (default)
      explode: true,          // default: true
    },
    allowReserved: false,      // default: false
  },
});

Custom Function

const client = createClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
  querySerializer(queryParams) {
    let s = "";
    for (const [k, v] of Object.entries(queryParams)) {
      if (v !== undefined) {
        s += `${s ? "&" : ""}${k}=${encodeURIComponent(String(v))}`;
      }
    }
    return s;
  },
});

Per-Request Override

const { data } = await client.GET("/search", {
  params: { query: { tags: ["a", "b", "c"] } },
  querySerializer: {
    array: { style: "pipeDelimited", explode: false },
  },
});

Body Serialization

FormData

const { data } = await client.POST("/upload", {
  body: { file: myFile, name: "photo" },
  bodySerializer(body) {
    const fd = new FormData();
    for (const [name, value] of Object.entries(body)) {
      fd.append(name, value);
    }
    return fd;
  },
});

URL-Encoded

Provide the content-type header and pass body as an object:

const { data } = await client.POST("/form", {
  body: { username: "user", password: "pass" },
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
});

Path Serialization

Custom path parameter formatting:

const client = createClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
  pathSerializer(pathname, pathParams) {
    let result = pathname;
    for (const [key, value] of Object.entries(pathParams)) {
      result = result.replace(`{${key}}`, encodeURIComponent(String(value)));
    }
    return result;
  },
});

Path-Based Client

Alternative API where methods are accessed via path:

import { createPathBasedClient, wrapAsPathBasedClient } from "openapi-fetch";
import type { paths } from "./my-schema";

// Option 1: Create directly (no middleware support)
const client = createPathBasedClient<paths>({ baseUrl: "https://myapi.dev/v1/" });
const { data } = await client["/blogposts/{post_id}"].GET({
  params: { path: { post_id: "123" } },
});

// Option 2: Wrap existing client (preserves middleware)
const baseClient = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });
baseClient.use(authMiddleware);
const pathClient = wrapAsPathBasedClient(baseClient);
const { data } = await pathClient["/blogposts"].GET();

Note: createPathBasedClient does not support middleware. Use wrapAsPathBasedClient with an existing client if you need middleware.

Testing

Mocking Requests with vi.fn / jest.fn

Supply a mock fetch to the client:

import createClient from "openapi-fetch";
import { expect, test, vi } from "vitest";
import type { paths } from "./my-schema";

test("my request", async () => {
  const mockFetch = vi.fn();
  const client = createClient<paths>({
    baseUrl: "https://my-site.com/api/v1/",
    fetch: mockFetch,
  });

  const reqBody = { name: "test" };
  await client.PUT("/tag", { body: reqBody });

  const req = mockFetch.mock.calls[0][0];
  expect(req.url).toBe("/tag");
  expect(await req.json()).toEqual(reqBody);
});

Mocking Responses with MSW

Mock Service Worker is recommended for mocking API responses:

import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import createClient from "openapi-fetch";
import { afterEach, beforeAll, afterAll, expect, test } from "vitest";
import type { paths } from "./my-schema";

const server = setupServer();

beforeAll(() => {
  server.listen({
    onUnhandledRequest: (request) => {
      throw new Error(`No request handler found for ${request.method} ${request.url}`);
    },
  });
});

afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test("my API call", async () => {
  const rawData = { test: { data: "foo" } };
  const BASE_URL = "https://my-site.com";

  server.use(
    http.get(`${BASE_URL}/api/v1/foo`, () =>
      HttpResponse.json(rawData, { status: 200 }),
    ),
  );

  const client = createClient<paths>({ baseUrl: BASE_URL });
  const { data, error } = await client.GET("/api/v1/foo");

  expect(data).toEqual(rawData);
  expect(error).toBeUndefined();
});

Important: server.listen() must be called before createClient is used so MSW can intercept requests.

Exported Types

Key types available from openapi-fetch:

import type {
  Client,
  ClientOptions,
  Middleware,
  FetchOptions,
  FetchResponse,
  MaybeOptionalInit,
  ParseAs,
  QuerySerializer,
  QuerySerializerOptions,
  BodySerializer,
  PathSerializer,
  HeadersOptions,
  MethodResponse,
  ClientPathsWithMethod,
  PathBasedClient,
} from "openapi-fetch";

MethodResponse — Extract Response Data Type

import type { MethodResponse } from "openapi-fetch";

// Extract the data type for a specific endpoint
type BlogPost = MethodResponse<typeof client, "get", "/blogposts/{post_id}">;

ClientPathsWithMethod — Get All Paths for a Method

import type { ClientPathsWithMethod } from "openapi-fetch";

type GettablePaths = ClientPathsWithMethod<typeof client, "get">;

MaybeOptionalInit — Init Type for a Path/Method

Determines whether the init parameter is required or optional based on the schema:

import type { MaybeOptionalInit } from "openapi-fetch";
import type { paths } from "./my-schema";

type BlogPostInit = MaybeOptionalInit<paths["/blogposts/{post_id}"], "get">;

Exported Utilities

Helper functions for custom serialization:

import {
  createQuerySerializer,
  defaultPathSerializer,
  defaultBodySerializer,
  createFinalURL,
  mergeHeaders,
  serializePrimitiveParam,
  serializeObjectParam,
  serializeArrayParam,
  removeTrailingSlash,
} from "openapi-fetch";

System Requirements

• Browsers: Modern browsers with Fetch API support
• Node.js: >= 18.0.0
• TypeScript: >= 4.7 (5.0+ recommended)