A TypeScript utility that converts Swagger/OpenAPI specifications into pure TypeScript types for type-safe API route handling. The generated types are completely erased at runtime, adding zero overhead to your JavaScript bundle.
Overview
swagger2types transforms your Swagger/OpenAPI specs into a structured TypeScript interface that provides:
Request/Response type mapping for each endpoint
Type-safe route definitions with body, query, header, and parameter types
Zero runtime cost - all types are erased during compilation
Before You Start
This is an advanced TypeScript tool that requires some understanding of:
TypeScript generics and mapped types
API client patterns and HTTP libraries
OpenAPI/Swagger specifications
- generates only TypeScript types. You'll need to implement your own API calling logic or use the provided helper utilities.
Not a traditional API client library
swagger2types
Best suited for developers who:
Want maximum control over their API client implementation
Value minimal bundle size and runtime overhead
Are comfortable with advanced TypeScript patterns
Prefer explicit API structure over abstracted method names
New to TypeScript or API clients? Consider starting with a full-featured library like swagger-typescript-api or openapi-generator before exploring this minimal approach.
Ready to proceed? Continue reading to understand how swagger2types works and see the examples for complete implementations.
Installation
npm install swagger2types
Usage
CLI Usage
# From a local fileswagger2types ./api-spec.json > generated/my-api.ts# From a URLswagger2types https://api.example.com/swagger.json > generated/my-api.ts# From stdincat api-spec.json | swagger2types > generated/my-api.ts
Programmatic Usage
import { generate } from 'swagger2types';import { writeFileSync } from 'fs';const spec = { // Your Swagger/OpenAPI spec openapi: '3.0.0', // ... rest of spec};const generated = await generate(spec);writeFileSync('./generated/my-api.ts', generated);
Generated Type Structure
The tool generates a Routes type that maps each API endpoint to its request and response types:
export type Routes = { /** Get a list of users with optional pagination */ ['GET /users']: { Request: { query?: { page?: number; limit?: number }; }; Response: User[]; }; /** Create a new post for a specific user */ ['POST /users/${userId}/posts']: { Request: { params: { userId: string }; body: CreatePostRequest; }; Response: Post; }; // ... more routes};
Each route includes JSDoc comments from your OpenAPI spec's description or summary fields, plus request types with only the properties it actually uses:
params - Path parameters (e.g., ${userId})
query - Query string parameters
headers - Required headers
body - Request body for POST/PUT/PATCH operations
But Why?
Preserves Your API Structure
Other generators create method-based clients (client.getUser(id)) that obscure the actual API structure. You end up hunting through documentation to figure out which method maps to GET /api/users/{userId}.
swagger2types keeps it simple: you work directly with routes as they appear in your API documentation. No abstraction layer, no guessing.
Minimal Bundle Impact
Traditional generators produce massive amounts of runtime code. For example, swagger-typescript-api generates over 1MB of TypeScript code for the GitHub API, resulting in 200KB+ of minified JavaScript that ships to users.
swagger2types generates only type definitions that disappear at compile time. Your bundle impact stays under 1KB regardless of API size - whether you have 10 endpoints or 1,000.
Choose your own HTTP client, error handling, response processing, and integration approach. Works seamlessly with any framework (React, Vue, Angular, Express, Next.js) and module system (ESM, CJS).
Integrate gradually with existing codebases - no need to refactor everything to use a specific client library. The examples show different approaches you can adapt.
Complete Example
Here's the typical workflow from spec to type-safe API calls: