openapi-shape

OpenAPI-shaped fetch. Generate a TypeScript module from an OpenAPI 3.0, 3.1, or 3.2 description. Call operations by "METHOD /path" with a typed fetch client built around standard Request and Response objects.

• Web standards. Send JSON, multipart forms with per-part encoding, Blobs, and streams. Add middleware for authentication, retries, and logging.
• Types for real APIs. Get named component schemas, typed request inputs, and responses that narrow by HTTP status. Documented compatibility rules handle common OpenAPI quirks.
• Small footprint. One generated .ts file and a dependency-free client.
• Controlled generation. Cancel work, bound document loading, and provide a custom loader for authenticated or cached sources.
• CI-ready. Use --check to catch outdated generated files.

Quick start

Install the package and generate a module from your API description:

pnpm add openapi-shape
pnpm exec openapi-shape ./openapi.yaml -o src/api.ts

The source can be a local JSON or YAML file or an HTTP(S) URL. External references resolve automatically. Import the generated contract to make a request:

import { createClient } from "openapi-shape/client"
import { contract } from "./api"

const api = createClient(contract, { baseUrl: "https://api.example.com/v1" })

const { data: pets, error } = await api.result("GET /pets", { query: { limit: 10 } })
if (error !== undefined) throw new Error(error?.message ?? "Could not load pets")

console.log(pets.map((pet) => pet.name)) // pets: Schemas.Pet[]

Use api.result() for decoded data or api.fetch() for a typed Response. See the client guide for response handling, middleware, and streams.

The generated module has no imports or runtime dependencies. Its Endpoints and Schemas types also work with your own client.

Requirements

• Generator: Node.js 22 or later.
• Client: a runtime with fetch support.

The generated module and client use ES modules. CommonJS is not supported. When updating, see contract compatibility for regeneration requirements.

Documentation

• The generated module: Endpoints, Webhooks, Callbacks, Schemas, and the runtime contract.
• Client: requests, responses, serialization, middleware, and typed wrappers.
• OpenAPI support: supported versions, references, schemas, media types, compatibility rules, and approximations.
• CLI and programmatic API: options, --check, generate(), and diagnostics.

Development

Run pnpm verify for tests, type checking, lint, and formatting checks. This also validates the compile-time assertions that pnpm test --run alone does not check.

License

MIT