Input Configuration

The input option specifies where to load your OpenAPI specification from. It supports local files, URLs, and API registry shorthands.

Basic Usage

export default defineConfig({
  input: './openapi.json',
  output: './src/client',
});

export default defineConfig({
  input: 'https://api.example.com/openapi.json',
  output: './src/client',
});

export default defineConfig({
  input: 'https://get.heyapi.dev/my-org/my-project',
  output: './src/client',
});

Input Options

For advanced scenarios, use an object to configure additional input options:

string | object

required

Path to the OpenAPI specification. Can be:

Local file path (e.g., './openapi.yaml')
URL (e.g., 'https://api.example.com/openapi.json')
API registry shorthand (e.g., 'org/project')
Parsed JSON object

Both JSON and YAML formats are supported.

RequestInit

Pass any valid Fetch API options to the request for fetching your specification. Useful for adding authentication headers.

export default defineConfig({
  input: {
    path: 'https://api.example.com/openapi.json',
    fetch: {
      headers: {
        Authorization: 'Bearer token',
      },
    },
  },
  output: './src/client',
});

boolean | number | object

default:false

Regenerate the client when the input file changes. Pass true to enable with default settings, or a number for custom interval in milliseconds.

Show Watch Configuration

boolean

default:false

Whether watch mode is enabled.

number

default:1000

How often to check for changes (in milliseconds).

number

default:60000

Request timeout when fetching remote specifications (in milliseconds).

export default defineConfig({
  input: {
    path: './openapi.yaml',
    watch: true, // or { enabled: true, interval: 2000 }
  },
  output: './src/client',
});

API Registry Options

When using Hey API Platform, additional options are available:

string

Organization created in Hey API Platform.Requires path to start with https://get.heyapi.dev or be undefined.

string

Project created in Hey API Platform.Requires path to start with https://get.heyapi.dev or be undefined.

string

API key for authenticating with Hey API Platform. Projects are private by default.You can also provide an environment variable HEY_API_TOKEN instead.Requires path to start with https://get.heyapi.dev or be undefined.

string

Fetch the last build from a specific branch.Requires path to start with https://get.heyapi.dev or be undefined.

string

Fetch an exact specification by commit SHA. This always returns the same file.Requires path to start with https://get.heyapi.dev or be undefined.

string

Fetch the last uploaded specification matching the OpenAPI version field value.Requires path to start with https://get.heyapi.dev or be undefined.

string[]

Filter specifications by custom tags. When multiple tags are provided, only the first match is returned.Requires path to start with https://get.heyapi.dev or be undefined.

API Registry Example

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: {
    path: 'https://get.heyapi.dev/my-org/my-project',
    api_key: process.env.HEY_API_TOKEN,
    branch: 'main',
    version: '1.0.0',
  },
  output: './src/client',
});

Multiple Inputs

You can provide an array of inputs to combine multiple OpenAPI specifications into a single output:

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: [
    './specs/users.yaml',
    './specs/products.yaml',
  ],
  output: './src/client',
});

When using multiple inputs with multiple outputs, the arrays must have the same length. Each input will be paired with the corresponding output.

Watch Mode

Watch mode is useful during development to automatically regenerate the client when your OpenAPI specification changes:

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: {
    path: './openapi.yaml',
    watch: {
      enabled: true,
      interval: 2000, // Check every 2 seconds
    },
  },
  output: './src/client',
});

For remote URLs, watch mode will poll the endpoint at the specified interval:

export default defineConfig({
  input: {
    path: 'https://api.example.com/openapi.json',
    watch: {
      enabled: true,
      interval: 5000, // Check every 5 seconds
      timeout: 30000, // 30 second timeout
    },
  },
  output: './src/client',
});

Supported Formats

OpenAPI TypeScript supports:

OpenAPI 3.0.x (JSON and YAML)
OpenAPI 3.1.x (JSON and YAML)
Swagger 2.0 (JSON and YAML)

Both .json and .yaml/.yml file extensions are automatically detected and parsed.

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

Basic Usage

Input Options

API Registry Options

API Registry Example

Multiple Inputs

Watch Mode

Supported Formats

​Basic Usage

​Input Options

​API Registry Options

​API Registry Example

​Multiple Inputs

​Watch Mode

​Supported Formats

Basic Usage

Input Options

API Registry Options

API Registry Example

Multiple Inputs

Watch Mode

Supported Formats