openapi-ts-client

Generate TypeScript clients from OpenAPI 3.x specifications.

Features

• Supports OpenAPI 3.0.x and 3.1.x specifications
• Three output formats: Fetch API, Axios, and Angular
• Fully typed TypeScript output with models and API classes
• Accepts specs as Python dictionaries or JSON strings
• Automatic validation of OpenAPI specifications

Why This Project?

Python backend frameworks like FastAPI and django-ninja already generate OpenAPI specs from your type hints. This library enables those frameworks to take the next step: generating TypeScript clients that mirror your backend types exactly. Framework authors can integrate openapi-ts-client to give their users end-to-end type safety with zero manual type definitions.

Installation

pip install openapi-ts-client

Or install from source:

git clone https://github.com/fa-krug/openapi-ts-client.git
cd openapi-ts-client
pip install -e .

CLI Usage

# Generate from file
openapi-ts-client ./openapi.json

# Specify output format and directory
openapi-ts-client ./openapi.json -f axios -o ./src/api

# Generate from URL
openapi-ts-client https://api.example.com/openapi.json

# Generate from stdin
cat openapi.json | openapi-ts-client -

# Use config file
openapi-ts-client --config ./my-config.json

# Verbose output
openapi-ts-client ./openapi.json -v

Config File

Create openapi-ts-client.json for repeated use:

{
  "clients": [
    {
      "input": "./specs/users-api.json",
      "format": "fetch",
      "output": "./src/api/users"
    },
    {
      "input": "./specs/orders-api.json",
      "format": "axios",
      "output": "./src/api/orders"
    }
  ]
}

Then run:

openapi-ts-client

Options

Quick Start

from openapi_ts_client import generate_typescript_client, ClientFormat

# Load your OpenAPI spec (from file, URL, or inline)
with open("openapi.json", "r") as f:
    spec = f.read()

# Generate a TypeScript client
result = generate_typescript_client(
    openapi_spec=spec,
    output_format=ClientFormat.FETCH,
    output_path="./generated/api"
)

print(result)
# Output: TypeScript Fetch client generated for 'My API' v1.0.0 (OpenAPI 3.0.0). Output: /path/to/generated/api

Usage

Basic Usage

from openapi_ts_client import generate_typescript_client, ClientFormat

# Inline OpenAPI 3.x specification
spec = {
    "openapi": "3.0.0",
    "info": {
        "title": "My API",
        "version": "1.0.0"
    },
    "paths": {
        "/users": {
            "get": {
                "summary": "Get all users",
                "operationId": "getUsers",
                "responses": {
                    "200": {
                        "description": "Success"
                    }
                }
            }
        }
    }
}

# Generate with defaults (Fetch client, temp directory)
result = generate_typescript_client(spec)

Loading from JSON File

from openapi_ts_client import generate_typescript_client

# Load spec from a JSON file (as string)
with open("openapi.json", "r") as f:
    json_string = f.read()

result = generate_typescript_client(json_string, output_path="./src/api")

Loading from YAML File

import yaml
from openapi_ts_client import generate_typescript_client

# Load spec from YAML (convert to dict)
with open("openapi.yaml", "r") as f:
    spec = yaml.safe_load(f)

result = generate_typescript_client(spec, output_path="./src/api")

Client Formats

The package supports three output formats, each optimized for different use cases:

Fetch API Client (Default)

Native browser Fetch API client with no external dependencies.

from openapi_ts_client import generate_typescript_client, ClientFormat

result = generate_typescript_client(
    spec,
    output_format=ClientFormat.FETCH,
    output_path="./generated/fetch-client"
)

Generated structure:

fetch-client/
├── index.ts          # Main entry point, exports all
├── runtime.ts        # HTTP client runtime utilities
├── apis/
│   ├── index.ts      # Exports all API classes
│   ├── PetApi.ts     # API class for /pet endpoints
│   ├── StoreApi.ts   # API class for /store endpoints
│   └── UserApi.ts    # API class for /user endpoints
└── models/
    ├── index.ts      # Exports all model interfaces
    ├── Pet.ts        # TypeScript interface for Pet
    ├── Order.ts      # TypeScript interface for Order
    └── User.ts       # TypeScript interface for User

Usage in TypeScript:

import { Configuration, PetApi, Pet } from './generated/fetch-client';

const config = new Configuration({
    basePath: 'https://api.example.com',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
});

const petApi = new PetApi(config);

// Get a pet by ID
const pet: Pet = await petApi.getPetById({ petId: 1 });

// Create a new pet
const newPet = await petApi.addPet({
    pet: { name: 'Fluffy', status: 'available' }
});

Axios Client

Client using the popular Axios HTTP library with interceptors support.

from openapi_ts_client import generate_typescript_client, ClientFormat

result = generate_typescript_client(
    spec,
    output_format=ClientFormat.AXIOS,
    output_path="./generated/axios-client"
)

Generated structure:

axios-client/
├── index.ts          # Main entry point
├── api.ts            # All API classes and interfaces
├── base.ts           # Base API class
├── common.ts         # Common utilities
└── configuration.ts  # Configuration class

Usage in TypeScript:

import { Configuration, PetApi } from './generated/axios-client';
import axios from 'axios';

const config = new Configuration({
    basePath: 'https://api.example.com',
    accessToken: 'YOUR_TOKEN'
});

const petApi = new PetApi(config);

// Get a pet by ID
const response = await petApi.getPetById(1);
const pet = response.data;

// With custom Axios instance (for interceptors)
const axiosInstance = axios.create();
axiosInstance.interceptors.request.use((config) => {
    config.headers.Authorization = `Bearer ${getToken()}`;
    return config;
});

const petApiWithInterceptors = new PetApi(config, undefined, axiosInstance);

Angular Client

Angular-optimized client with injectable services and RxJS Observables.

from openapi_ts_client import generate_typescript_client, ClientFormat

result = generate_typescript_client(
    spec,
    output_format=ClientFormat.ANGULAR,
    output_path="./generated/angular-client"
)

Generated structure:

angular-client/
├── index.ts              # Main entry point
├── api.module.ts         # Angular module for importing
├── api.base.service.ts   # Base service class
├── configuration.ts      # Configuration class
├── provide-api.ts        # Standalone provider function
├── api/
│   ├── api.ts            # Exports all services
│   ├── pet.service.ts    # Injectable PetService
│   ├── store.service.ts  # Injectable StoreService
│   └── user.service.ts   # Injectable UserService
└── model/
    ├── models.ts         # Exports all models
    ├── pet.ts            # Pet interface
    ├── order.ts          # Order interface
    └── user.ts           # User interface

Usage in Angular:

// app.module.ts
import { ApiModule, Configuration } from './generated/angular-client';

@NgModule({
    imports: [
        ApiModule.forRoot(() => new Configuration({
            basePath: 'https://api.example.com'
        }))
    ]
})
export class AppModule { }

// Or with standalone components (Angular 14+)
// app.config.ts
import { provideApi } from './generated/angular-client';

export const appConfig = {
    providers: [
        provideApi({
            basePath: 'https://api.example.com'
        })
    ]
};

// pet.component.ts
import { Component, inject } from '@angular/core';
import { PetService, Pet } from './generated/angular-client';

@Component({
    selector: 'app-pet',
    template: `<div>{{ pet?.name }}</div>`
})
export class PetComponent {
    private petService = inject(PetService);
    pet: Pet | null = null;

    ngOnInit() {
        this.petService.getPetById(1).subscribe(pet => {
            this.pet = pet;
        });
    }
}

API Reference

generate_typescript_client(openapi_spec, output_format, output_path)

Generate a TypeScript client from an OpenAPI specification.

Parameters:

Returns:

• str: A status message with generation details

Raises:

• ValueError: If the specification is invalid or missing required fields
• TypeError: If openapi_spec is neither a dict nor a string

ClientFormat Enum

Supported OpenAPI Features

Versions

• OpenAPI 3.0.x
• OpenAPI 3.1.x

Schema Types

• Primitive types (string, number, integer, boolean)
• Arrays and objects
• Enums
• $ref references
• allOf, anyOf, oneOf compositions
• Nullable types

Operations

• All HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
• Path parameters
• Query parameters
• Request bodies (JSON, form data)
• Response types
• Operation tags (for grouping into API classes)

Security

• API Key authentication
• Bearer token authentication
• OAuth2 flows
• Basic authentication

Requirements

• Python 3.8+

Runtime dependencies:

• jinja2>=3.1.0 - Template engine
• openapi-core>=0.19.0 - OpenAPI spec validation

For using generated clients:

• Node.js with TypeScript
• Axios (for Axios client)
• Angular 14+ (for Angular client)

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff check src --fix
ruff format src

# Setup pre-commit hooks
pre-commit install

Acknowledgements

This project builds on the excellent work of the OpenAPI Generator team. Their years of effort creating robust code generation templates provided the foundation that made openapi-ts-client possible. Thank you for your contributions to the open-source community.

License

MIT License - see LICENSE for details.

Links

• GitHub Repository
• Issue Tracker