openapi-typesafe
/openapi-typesafe
Generate TypeScript types from an OpenAPI 3.x document with openapi-typesafe and call the API through openapi-typesafe-fetch or openapi-typesafe-react-query with fully inferred types. Use when a project depends on openapi-typesafe, openapi-typesafe-fetch or openapi-typesafe-react-query; when moving a project off openapi-typescript, openapi-fetch or openapi-react-query; when openapi-typescript fails with TypeScript 7; or when writing typed API calls, middleware, auth or error handling for an OpenAPI client.
- Author
- openapi-typesafe ↗
- Repository
- openapi-typesafe ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Generate TypeScript types from an OpenAPI 3.x document with openapi-typesafe and call the API through openapi-typesafe-fetch or openapi-typesafe-react-query with fully inferred types. Use when a project depends on openapi-typesafe, openapi-typesafe-fetch or openapi-typesafe-react-query; when moving a project off openapi-typescript, openapi-fetch or openapi-react-query; when openapi-typescript fails with TypeScript 7; or when writing typed API calls, middleware, auth or error handling for an OpenAPI client.
Original author description
Generate TypeScript types from an OpenAPI 3.x document with openapi-typesafe and call the API through openapi-typesafe-fetch or openapi-typesafe-react-query with fully inferred types. Use when a project depends on openapi-typesafe, openapi-typesafe-fetch or openapi-typesafe-react-query; when moving a project off openapi-typescript, openapi-fetch or openapi-react-query; when openapi-typescript fails with TypeScript 7; or when writing typed API calls, middleware, auth or error handling for an OpenAPI client.
How it works
- 1. Generate the types
- 2. Create the client
- 3. Call an endpoint
- 4. Handle the result
- 5. Middleware
- 6. Reusable types
- 7. Testing code that calls the client
- Common mistakes
SKILL.md preview
---
name: openapi-typesafe
description: Generate TypeScript types from an OpenAPI 3.x document with openapi-typesafe and call the API through openapi-typesafe-fetch or openapi-typesafe-react-query with fully inferred types. Use when a project depends on openapi-typesafe, openapi-typesafe-fetch or openapi-typesafe-react-query; when moving a project off openapi-typescript, openapi-fetch or openapi-react-query; when openapi-typescript fails with TypeScript 7; or when writing typed API calls, middleware, auth or error handling for an OpenAPI client.
license: MIT
---
# openapi-typesafe
openapi-typesafe turns an OpenAPI 3.0, 3.1 or 3.2 document into TypeScript types. It is a drop-in
successor to openapi-typescript 7.13 that also works with TypeScript 7. Five packages share one
version number:
| Package | Role | Replaces |
| :-- | :-- | :-- |
| `openapi-typesafe` | Generator: CLI and Node API (dev dependency) | `openapi-typescript` |
| `openapi-typesafe-fetch` | Typed `fetch` client, about 11 kB minified | `openapi-fetch` |
| `openapi-typesafe-react-query` | TanStack Query v5 hooks on top of the client, about 4 kB minified | `openapi-react-query` |
| `openapi-typesafe-helpers` | Shared utility types | `openapi-typescript-helpers` |
| `openapi-typesafe-migrate` | One-off migration command, run with `npx` | none |
Requirements: Node.js 22.12+ for the generator, Node.js 22+ (or a browser, Bun, Deno) for the
client, TypeScript 5.4 or newer (6.x and 7.x included).
Pick the task:
- New setup or typed calls: read on.
- Moving a project from openapi-typescript / openapi-fetch / openapi-react-query, or a
TypeScript 7 error: [references/migration.md](references/migration.md).
- React components with TanStack Query: [references/react-query.md](references/react-query.md).
- Generator options, Node API, callbacks, error codes:
[references/generator.md](references/generator.md).
## 1. Generate the types
```bash
npm i openapi-typesafe-fetch
npm i -D openapi-typesafe
npx openapi-typesafe ./openapi.yaml -o ./src/api/schema.d.ts
```
- Add a script, for example `"generate:api": "openapi-typesafe ./openapi.yaml -o ./src/api/schema.d.ts"`.
- The output exports `paths`, `components`, `operations` and `webhooks`. Never edit it by hand:
change the OpenAPI document and regenerate.
- In CI, `openapi-typesafe ./openapi.yaml -o ./src/api/schema.d.ts --check` exits with `1` when the
file is stale.
- Turn on `noUncheckedIndexedAccess` in `tsconfig.json`; additional properties are then typed as
possibly `undefined`.
## 2. Create the client
```ts
import createClient from "openapi-typesafe-fetch";
import type { paths } from "./api/schema"; // generated file
export const client = createClient<paths>({ baseUrl: "https://api.example.com/v1" });
```
Create one client per base URL and reuse it. `createClient` also takes `headers` (sent with every
request), `fetch` (a custom fetch, used in tests), `querySerializer`, `bodySerializer`, `requestInitExt`
(the second `fetch` argument on Node.js, such as an undici `dispatcher`) and any `RequestInit`
field such as `credentials`.
## 3. Call an endpoint
The path string must be the literal key from the document, with its `{placeholders}`. Never build
it at run time: type inference works only on the literal.
```ts
const { data, error, response } = await client.GET("/pets/{petId}", {
params: {
path: { petId: 42 },
query: { include: "owner" },
},
});
const created = await client.POST("/pets", {
body: { name: "Rex", tag: "dog" },
});
```
- Methods are upper-case: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, `TRACE`,
and `QUERY` for OpenAPI 3.2 `query` operations (it takes a `body` like `POST`). Methods under
`additionalOperations` (3.2) are typed but not callable through the client.
- Parameters go under `params`, grouped by location: `path`, `query`, `header`, `cookie`.
Never put a path or query value at the top level of the options.
- The request body is `body`, a plain object for JSON. The client serializes it; do not call
`JSON.stringify` yourself.
- The client sends `Content-Type: application/json` unless you set another one; it does not read
the media type from the document. Raw bodies (`FormData`, `Blob`, `URLSearchParams`,
`ArrayBuffer`, typed arrays) get no default `Content-Type`; the platform sets it. For other bodies set the header in `headers`:
- text: `body: notes, headers: { "Content-Type": "text/plain" }`; a string is then sent as is
(with a JSON type it would be a JSON string, in quotes);
- form: `headers: { "Content-Type": "application/x-www-form-urlencoded" }` with a plain object;
- files (`multipart/form-data`): generate with `--binary-as-blob` (file fields become `Blob`),
set `headers: { "Content-Type": "multipart/form-data" }` and pass the typed object as `body`;
the client builds the `FormData` and `fetch` adds the boundary. Nested objects need a
`bodySerializer`.
- The second argument is required only when the operation has required parameters or a required
body.
- Do not pass generics to `GET` / `POST` and do not cast the result. Everything is inferred from
`paths`; a cast hides the bugs the types exist to catch.
- `parseAs: "text" | "blob" | "arrayBuffer" | "stream"` changes how a success body is read
(default `"json"`).
- Per-request `headers`, `signal`, `baseUrl` and `fetch` override the client options. Headers can
be a record, a `Headers` object or a list of pairs; `null` removes a client header, and
`params.header` wins over both.
- A path parameter that makes a `.` or `..` segment, or an empty first segment (`//host`), throws
before the request.
## 4. Handle the result
Every call resolves to `{ data, error, response }`. It does not throw for HTTP errors. It rejects
when `fetch` itself fails (network error, CORS, abort), when a middleware throws, and when a
success body is not JSON (a proxy's HTML page gives a `SyntaxError`; set `parseAs: "text"` for
such a response).
| Field | Value |
| :-- | :-- |
| `data` | Parsed `2xx` body; `undefined` otherwise |
| `error` | Parsed body of any other status (`1xx`, `3xx`, `4xx`, `5xx`, `default`); `undefined` otherwise |
| `response` | The original `Response` (`status`, `headers`, `ok`) |
An error response **without a body** has `error: undefined`, and so does any `204` or `HEAD`
response. So `if (error)` alone misses an empty `500`. Check `response.ok`:
```ts
async function loadPet(petId: number) {
const { data, error, response } = await client.GET("/pets/{petId}", {
params: { path: { petId } },
});
if (!response.ok) {
// `error` is the typed error body, or undefined when the server sent none.
throw new ApiError(response.status, error);
}
return data; // the 2xx body, or undefined for an empty body (`response` does not narrow it)
}
```
- Narrow on `error` before you read `data`: `data` and `error` are a discriminated union, and
`response` is not part of it, so `response.ok` does not narrow `data`.
- Branch on `response.status` for status-specific handling; the `error` type is the union of all
error bodies of the operation.
- An error body is parsed only when its `Content-Type` is JSON (or missing and the body parses);
any other error body, such as `text/plain` or HTML, comes back as text in `error`. A success
body that is not JSON rejects (see above).
- Network failures and aborts reject: wrap the call in `try` / `catch` where you need to handle
them, or turn them into a value with `onError` middleware (section 5).
## 5. Middleware
Middleware sees every request of a client. Register it with `client.use(...)` and remove it with
`client.eject(...)`.
```ts
import createClient, { type Middleware } from "openapi-typesafe-fetch";
const authMiddleware: Middleware = {
async onRequest({ request }) {
request.headers.set("Authorization", `Bearer ${await tokens.current()}`);
return request;
},
};
client.use(authMiddleware);
```
- `onRequest({ request, schemaPath, params, id, options })`: return a `Request` to replace it,
return a `Response` to skip the network (cache, mock), or return nothing to leave it as is.
- `onResponse({ request, response, ... })`: return a new `Response` to replace it, or nothing.
To read the body, read `response.clone()`: the client still has to read the original.
- `onError({ error, ... })`: called when `fetch` throws. Return nothing to rethrow, an `Error` to
throw that error instead, or a `Response` to recover.
- `onRequest` runs in registration order; `onResponse` runs in reverse order.
- `schemaPath` is the document path such as `"/pets/{petId}"`; use it to skip middleware for some
endpoints (for example no auth header on `/auth/login`).
- Pass `middleware: [m]` in the options of a single call to apply it to that call only.
- Throwing in `onResponse` when `!response.ok` turns HTTP errors into rejections. Do this only
when the caller wants exceptions (for example in a TanStack Query `queryFn` that does not use
openapi-typesafe-react-query).
## 6. Reusable types
```ts
import type { components, operations, paths } from "./api/schema";
type Pet = components["schemas"]["Pet"];
type NewPet = paths["/pets"]["post"]["requestBody"]["content"]["application/json"];
type PetResponse =
paths["/pets/{petId}"]["get"]["responses"][200]["content"]["application/json"];
type ListPetsQuery = operations["listPets"]["parameters"]["query"];
```
From `openapi-typesafe-helpers`: `PathsWithMethod<paths, "get">` (paths that have a GET),
`SuccessResponseJSON<Op>`, `ErrorResponseJSON<Op>`, `RequestBodyJSON<Op>`.
From `openapi-typesafe-fetch`: `MethodResponse<typeof client, "get", "/pets">` (the `data` type of
a call), `ClientPathsWithMethod<typeof client, "get">`.
## 7. Testing code that calls the client
Inject the client or its `fetch`, and answer with real `Response` objects. Do not mock the client
methods.
```ts
const requests: Request[] = [];
const client = createClient<paths>({
baseUrl: "https://api.example.com/v1",
fetch: async (request) => {
requests.push(request);
return Response.json({ id: 1, name: "Rex" }, { status: 200 });
},
});
```
The `fetch` option receives one `Request`; read `request.url`, `request.method`,
`request.headers` and `await request.json()` in assertions. Mock Service Worker (`msw`) also
works.
## Common mistakes
| Mistake | Fix |
| :-- | :-- |
| `client.GET(\`/pets/${id}\`)` | `client.GET("/pets/{petId}", { params: { path: { petId: id } } })` |
| `client.get(...)` | Methods are upper-case on the client: `client.GET(...)`; lower-case only in react-query hooks (`$api.useQuery("get", ...)`) |
| `{ query: { limit: 10 } }` at the top level | `{ params: { query: { limit: 10 } } }` |
| `body: JSON.stringify(pet)` | `body: pet` |
| `if (error) ...` as the only failure check | `if (!response.ok) ...`; `error` is `undefined` for an empty error body |
| `try { await client.GET(...) } catch` to catch a 404 | HTTP errors resolve; they do not throw. Check `response.ok` |
| `client.GET<Pet>(...)`, `data as Pet` | Remove the generic and the cast; fix the document if the type is wrong |
| Reading `data` without narrowing | Check `error` / `response.ok` first, or use `data!` only after that check |
| Editing the generated `schema.d.ts` | Change the OpenAPI document, regenerate |
| `import ... from "openapi-fetch"` / `"openapi-typescript"` | The packages are `openapi-typesafe-fetch` / `openapi-typesafe`; see the migration reference |
| `await response.json()` in `onResponse` | Read `response.clone().json()`; the client reads the original |
| A new client per request | Create the client once per base URL and reuse it |
| Installing `typescript@5` only to run the generator | Not needed: the generator has no TypeScript dependency |
Files in this package (4)
- SKILL.md 12 KB
- references/generator.md 11 KB
- references/migration.md 8 KB
- references/react-query.md 6 KB
Versions
The database has no other skills named openapi-typesafe.
Database snapshot: 13.11.2026 · package version dd5b71340222 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100openapi-to-typescript
Converts OpenAPI 3.0 JSON/YAML to TypeScript interfaces and type guards. This skill should be used when the user asks to generate types from OpenAPI, convert schema to TS, create API interfaces, or generate TypeScript types from an API specification. - 100openapi-spec
OpenAPI is the standard format for describing HTTP APIs in YAML or JSON, from which docs, typed clients and mock servers can be generated. Use this skill to write an OpenAPI 3.1 spec, lint it with Redocly CLI, generate TypeScript types and a typed fetch client, build HTML docs,… - 100openapi-codegen
OpenAPI client code generation. Covers openapi-typescript, openapi-generator-cli, swagger-typescript-api, and trpc-openapi. Use for generating type-safe API clients. USE WHEN: user mentions "OpenAPI codegen", "generate API client", "openapi-typescript", "swagger-typescript-api",… - 100type-generation
Automatic type generation from OpenAPI and GraphQL schemas. Covers openapi-typescript, graphql-codegen, and contract sync. USE WHEN: user asks about "openapi-typescript", "graphql-codegen", "generate types from API", "type generation", "API types", "schema to TypeScript" DO NOT… - 100api-contract
OpenAPI-first contract between a Spring Boot backend and TypeScript clients: generate the spec with springdoc-openapi 3.x, commit it as the source of truth, generate typed clients (openapi-typescript with openapi-fetch for React and Next.js, ng-openapi-gen or openapi-generator… - 100rest-api-generator
ATC REST API source generator and CLI for producing server endpoints, C# clients, and TypeScript clients from OpenAPI specifications. Use when the user asks to generate a REST API from an OpenAPI spec, scaffold server handlers, create typed HTTP clients, generate TypeScript…