Quick Start

Generate Your First Client

The fastest way to use OpenAPI TypeScript is with npx. No installation required.

Run the Generator

Use npx to generate your client directly from your OpenAPI specification:

npx @hey-api/openapi-ts -i path/to/openapi.json -o src/client

You can also use a URL:

npx @hey-api/openapi-ts -i https://api.example.com/openapi.json -o src/client

Or use the Hey API Registry (sign up at app.heyapi.dev):

npx @hey-api/openapi-ts -i hey-api/backend -o src/client

Review Generated Files

The generator creates several files in your output directory:

src/client/
├── sdk.gen.ts       # Type-safe SDK functions
├── types.gen.ts     # TypeScript interfaces
├── schemas.gen.ts   # JSON schemas
└── client.ts        # HTTP client configuration

Treat the output folder as a dependency. Don’t manually edit generated files as your changes will be overwritten on the next run.

Configure the Client

Set up your HTTP client with your API’s base URL:

import { client } from './client/client';

client.setConfig({
  baseUrl: 'https://api.example.com',
});

You can also configure headers, interceptors, and other options:

client.setConfig({
  baseUrl: 'https://api.example.com',
  headers: {
    Authorization: 'Bearer YOUR_TOKEN',
  },
});

Use the Generated SDK

Import and use the generated SDK functions:

import { getPets, createPet } from './client/sdk.gen';

// Fetch data with full type safety
const { data, error } = await getPets({
  query: {
    limit: 10,
    status: 'available',
  },
});

if (error) {
  console.error('Failed to fetch pets:', error);
  return;
}

console.log('Pets:', data);

// Create a new pet
const { data: newPet, error: createError } = await createPet({
  body: {
    name: 'Fluffy',
    status: 'available',
  },
});

Congratulations on creating your first client! 🎉

Example: Using with React

Here’s a complete example of using OpenAPI TypeScript in a React application:

import { useEffect, useState } from 'react';
import { client } from './client/client';
import { getPets } from './client/sdk.gen';
import type { Pet } from './client/types.gen';

// Configure client once
client.setConfig({
  baseUrl: 'https://petstore.swagger.io/v2',
});

function PetList() {
  const [pets, setPets] = useState<Pet[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchPets() {
      const { data, error } = await getPets({
        query: { limit: 10 },
      });

      if (error) {
        console.error('Failed to fetch pets:', error);
        setLoading(false);
        return;
      }

      setPets(data);
      setLoading(false);
    }

    fetchPets();
  }, []);

  if (loading) return <div>Loading...</div>;

  return (
    <ul>
      {pets.map((pet) => (
        <li key={pet.id}>{pet.name}</li>
      ))}
    </ul>
  );
}

For React applications, consider using the @tanstack/react-query plugin for automatic data fetching, caching, and state management. See the TanStack Query plugin documentation.

Working with Different Input Formats

OpenAPI TypeScript supports multiple input formats:

Local File
Remote URL
Hey API Registry

npx @hey-api/openapi-ts -i ./specs/openapi.yaml -o src/client

npx @hey-api/openapi-ts -i https://api.example.com/openapi.json -o src/client

If using HTTPS with a self-signed certificate in development, set NODE_TLS_REJECT_UNAUTHORIZED=0 in your environment.

npx @hey-api/openapi-ts -i your-org/your-api -o src/client

CLI Options

The CLI supports several options for quick configuration:

npx @hey-api/openapi-ts [options]

Options:
  -i, --input <path>      OpenAPI specification (path, URL, or string)
  -o, --output <path>     Output folder
  -c, --client <name>     HTTP client to generate
  -p, --plugins [names]   Plugins to use
  -f, --file <path>       Path to config file
  -d, --debug             Enable debug logging
  -s, --silent            Suppress all output
  -l, --logs <path>       Logs folder path
  --no-log-file           Disable log file output
  --dry-run               Skip writing files
  -w, --watch [interval]  Watch for changes
  -h, --help              Display help
  -v, --version           Display version

Example with Options

npx @hey-api/openapi-ts \
  -i https://petstore.swagger.io/v2/swagger.json \
  -o src/client \
  -c @hey-api/client-fetch \
  -p @hey-api/sdk @hey-api/typescript zod

Next Steps

Now that you’ve generated your first client, explore these topics:

Installation

Install as a dev dependency for use in scripts

Configuration

Learn about configuration files and advanced options

Plugins

Discover plugins for schemas, hooks, and frameworks

HTTP Clients

Choose the right HTTP client for your project

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

Generate Your First Client

Example: Using with React

Working with Different Input Formats

CLI Options

Example with Options

Next Steps

Installation

Configuration

Plugins

HTTP Clients

​Generate Your First Client

​Example: Using with React

​Working with Different Input Formats

​CLI Options

​Example with Options

​Next Steps

Installation

Configuration

Plugins

HTTP Clients

Generate Your First Client

Example: Using with React

Working with Different Input Formats

CLI Options

Example with Options

Next Steps