Swagger and OpenAPI JSON to TypeScript — Generating Types From a Schema

Swagger (now called OpenAPI) documents are the formal specification of a REST API. Done well, they describe every endpoint, every request body, every response shape, every status code, and every error variant. When you have a real OpenAPI document, you can generate a complete TypeScript client — every type, every function, type-safe end to end.

Our sample-based generator is the opposite approach: one paste, one interface, one shape. Here's when each is the right tool, and how they fit together.

What an OpenAPI Document Gives You That a Sample Can't

A single JSON sample shows one response from one request. An OpenAPI document describes:

• Every endpoint path and method
• Every parameter (path, query, header, body)
• Every possible response shape per status code
• Required vs optional fields, explicitly
• Nullable fields, explicitly
• Enum values for string fields
• Discriminated unions via oneOf / anyOf
• Formats (date-time, email, UUID) that a plain sample can't distinguish

Sample-based generation gets you 80% of what a typical endpoint returns. Schema-based generation gets you the full contract, including edge cases that don't appear in your sample.

Schema-Based Generation Tools

The schema-to-types ecosystem has several well-maintained options:

• openapi-typescript: Generates types from OpenAPI 3 documents. No runtime code, just types. Lightweight, fast, widely used.
• openapi-zod-client: Generates both types and a Zod-validated HTTP client. More runtime, more safety.
• Orval: Generates React Query, SWR, or Angular clients from OpenAPI. Integrates with your data-fetching library.
• Quicktype: Handles JSON Schema (and OpenAPI schemas embedded in a document) across 20+ target languages.
• json-schema-to-typescript: Generates TypeScript from plain JSON Schema (not full OpenAPI).

These are all CLIs or libraries. You point them at a schema URL or file; they produce types (and sometimes a client) that you commit or regenerate in CI.

Sell Custom Apparel — We Handle Printing & Free Shipping

When Sample-Based Is Still the Right Choice

Three scenarios where the sample-based browser tool beats the schema pipeline:

1. The API has no OpenAPI document. Surprisingly common — especially with smaller SaaS products, internal APIs, and anything older than about 2018. If you can't get a schema, sample-based is your only option.

2. The schema is wrong or incomplete. Also common. The OpenAPI document says createdAt: string but production always returns Date | null. Sample-based types what actually ships; schema-based types what was supposed to ship. When they disagree, production wins.

3. You need one type, not thirty. You're building a quick integration with one endpoint. A full OpenAPI generator produces types for every endpoint in the spec, most of which you don't use. The sample-based tool gives you just the one you want.

For these cases, paste the response into our JSON to TypeScript generator and move on.

Hybrid Workflow — Use Both

You don't have to pick. Most teams end up using both tools at different moments:

Sample-based for exploration. You're trying a new API. Hit the endpoint, paste the response, generate a type, see what it looks like. Throwaway work — you don't commit the type yet, you're just reading.

Schema-based for committed integration. Once you've decided to build against the API, set up openapi-typescript (or similar) in your build pipeline. Types regenerate on every build; they stay in sync with the spec automatically.

Sample-based for debugging. Production returns something that doesn't match your generated types. Paste the actual response into the sample-based tool and compare its output to what your schema-based types produce. The diff tells you whether the API drifted or your schema is wrong.

Each tool fits a different part of the lifecycle. Treating them as competing is a false choice.

When to Push for an OpenAPI Spec

If you're integrating with an internal team's API and they don't ship an OpenAPI document, it's worth asking for one. The argument:

• Generated clients eliminate a whole category of bugs
• Types stay in sync automatically — no more "hey, the shape of /users changed"
• The spec doubles as documentation
• Most modern backend frameworks (NestJS, FastAPI, ASP.NET) can generate the OpenAPI doc from the code itself, so it's near-zero overhead

For external APIs, you're stuck with whatever they publish. OpenAPI adoption has improved a lot over the last five years — most serious SaaS products ship a spec now — but a notable chunk of the API world still doesn't. Sample-based generation is the fallback that keeps working regardless.

Frequently Asked Questions

What is the difference between Swagger and OpenAPI?

OpenAPI is the spec; Swagger is the original name and a suite of tools around it. OpenAPI 3.0 and 3.1 are the current versions of the spec.

Can your browser tool read an OpenAPI document?

Not directly — our tool takes a JSON sample (a response body), not a schema document. For schema-based generation, use openapi-typescript or Quicktype.

Which tool should I use for an API that ships an OpenAPI spec?

openapi-typescript for just types, or Orval if you also want a generated data-fetching client. Both are CLIs you add to your build pipeline.

What if the OpenAPI spec is wrong?

This happens. Generate from the spec, then compare against a real response using a sample-based tool. If they disagree, either fix the spec or type from the sample until the spec is corrected.