Configuration

@hey-api/openapi-ts supports loading configuration from any file inside your project root folder supported by jiti loader. Below are the most common file formats.

openapi-ts.config.ts

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

export default defineConfig({
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
});

openapi-ts.config.cjs

/** @type {import('@hey-api/openapi-ts').UserConfig} */
module.exports = {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
};

openapi-ts.config.mjs

/** @type {import('@hey-api/openapi-ts').UserConfig} */
export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
};

Alternatively, you can use openapi-ts.config.js and configure the export statement depending on your project setup.

Input

Input is the first thing you must define. It can be a local path, remote URL, or a string content resolving to an OpenAPI specification. Hey API supports all valid OpenAPI versions and file formats.

INFO

We use @apidevtools/json-schema-ref-parser to resolve file locations. Please note that accessing a HTTPS URL on localhost has a known workaround.

Filters

WARNING

Filters work only with the experimental parser which is currently an opt-in feature.

If you work with large specifications and want to generate output from their subset, set input.include to a regular expression string matching against resource references.

export default {
  client: '@hey-api/client-fetch',
  experimentalParser: true, 
  input: {
    include: '^(#/components/schemas/foo|#/paths/api/v1/foo/get)$', 
    path: 'path/to/openapi.json',
  },
  output: 'src/client',
};

The configuration above will process only the schema named foo and GET operation for the /api/v1/foo path.

Output

Output is the next thing to define. It can be either a string pointing to the destination folder or a configuration object containing the destination folder path and optional settings (these are described below).

TIP

You should treat the output folder as a dependency. Do not directly modify its contents as your changes might be erased when you run @hey-api/openapi-ts again.

Formatting

To format your output folder contents, set output.format to a valid formatter.

disabled

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: {
    format: false, 
    path: 'src/client',
  },
};

prettier

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: {
    format: 'prettier', 
    path: 'src/client',
  },
};

biome

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: {
    format: 'biome', 
    path: 'src/client',
  },
};

You can also prevent your output from being formatted by adding your output path to the formatter's ignore file.

Linting

To lint your output folder contents, set output.lint to a valid linter.

disabled

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: {
    lint: false, 
    path: 'src/client',
  },
};

eslint

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: {
    lint: 'eslint', 
    path: 'src/client',
  },
};

biome

export default {
  client: '@hey-api/client-fetch',
  input: 'path/to/openapi.json',
  output: {
    lint: 'biome', 
    path: 'src/client',
  },
};

You can also prevent your output from being linted by adding your output path to the linter's ignore file.

Clients

Clients are responsible for sending the actual HTTP requests. The client value is not required, but you must define it if you're generating the service layer (enabled by default).

You can learn more on the Clients page.

Plugins

Plugins are responsible for generating artifacts from your input. By default, Hey API will generate TypeScript interfaces, JSON Schemas, and services from your OpenAPI specification. You can add, remove, or customize any of the plugins. In fact, we highly encourage you to do so!

You can learn more on the Output page.

Parser

If you're using OpenAPI 3.0 or newer, we encourage you to try out the experimental parser. In the future it will become the default parser, but until it's been tested it's an opt-in feature. To try it out, set the experimentalParser flag in your configuration to true.

config

export default {
  client: '@hey-api/client-fetch',
  experimentalParser: true, 
  input: 'path/to/openapi.json',
  output: 'src/client',
};

cli

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

The experimental parser produces a cleaner output while being faster than the legacy parser. It also supports features such as Filters and more will be added in the future.

The legacy parser will remain enabled for the legacy clients regardless of the experimentalParser flag value. However, it's unlikely to receive any further updates.

Config API

You can view the complete list of options in the UserConfig interface.

Examples

You can view live examples on StackBlitz.

Sponsoring

Love Hey API? Please consider becoming a sponsor.