Skip to content
CodeWithAgents OpenAPICodeWithAgents OpenAPI

Introduction

A TypeScript OpenAPI toolchain that turns a spec into everything you need: types, a fetch client, React Query hooks, Zod schemas, a server-side service interface, MSW mock handlers, and form error mapping. Every generated file compiles under strict: true with zero runtime wrapper dependencies. The pipeline is tested against 128 real-world specs (Stripe, GitHub, Spotify, OpenAI, and more) on every PR.

The pipeline

Section titled “The pipeline”
The CodeWithAgents OpenAPI package pipelineAn OpenAPI spec feeds openapi-zod-ts, which produces TypeScript types, Zod schemas, and a fetch client. The fetch client feeds openapi-react-query for React Query hooks and openapi-server for a typed service interface and router. api-errors is a runtime package that maps any API error shape to form field errors.OpenAPI specopenapi-zod-tsTypeScript typesmodels.tsZod schemasyours to extendFetch clientclient.tsopenapi-react-queryReact Query v5 hooksopenapi-serverservice interface + routerapi-errorsRuntime, no codegen. Maps any API error shape to form fields.

Everything flows from a single spec. One source of truth. When the spec changes, re-run the generator and the TypeScript compiler tells you exactly what broke.

Packages

Section titled “Packages”
PackageWhat it does
openapi-zod-tsGenerates TypeScript interfaces, a native fetch client, and optional Zod schemas
@codewithagents/openapi-react-queryGenerates typed React Query v5 hooks from the client openapi-zod-ts produces
@codewithagents/openapi-serverGenerates a typed service interface and an optional router (hono | express | fastify | none, default none)
@codewithagents/openapi-mswGenerates MSW v2 HTTP handlers with seeded Faker mock data from your spec
@codewithagents/api-errorsMaps API error responses to form field errors at runtime (no codegen step)

Each package is independent. Use only the ones your project needs. They share one spec and one output directory when used together.

Who it is for

Section titled “Who it is for”

Built for TypeScript projects that want end-to-end type safety from an OpenAPI spec. It works with any HTTP framework on the server side and any React setup on the client. The generated output is plain TypeScript: no axios, no wrapper libraries, nothing added to your runtime bundle beyond what you already use.

If your team maintains an OpenAPI spec, the toolchain turns it into a first-class TypeScript artifact at codegen time rather than leaving the gap between spec and code to manual effort.

Prerequisites

Section titled “Prerequisites”
  • Node.js 18 or later
  • An OpenAPI 3.1 spec (JSON or YAML). OpenAPI 3.0.x is well-supported in practice: 8 of the 13 showcase specs are 3.0.x and all compile. 3.0-only constructs like nullable: true are normalized to the 3.1 null-union form, so nullable fields produce the correct T | null types.
  • TypeScript with strict: true recommended (all generated output passes it out of the box)

Next step

Section titled “Next step”

Follow the Quickstart to go from a spec file to a working typed client in a few minutes.

ImpressumDatenschutz© CodeWithAgents