Quick Start

Get started with OpenAPI TypeScript in under 60 seconds

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:

Local File

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

Remote URL

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.

Hey API Registry

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

Sign up at app.heyapi.dev to manage your specs in the cloud.

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