Skip to main content

​
Generate Your First Client

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

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
2

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.
3

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',
  },
});
4

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: 
npx @hey-api/openapi-ts -i ./specs/openapi.yaml -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

Build docs developers (and LLMs) love

Get started for freeTalk to us