Configuration

@hey-api/openapi-ts supports loading configuration from any file inside your project root directory 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({
  input: 'path/to/openapi.json',
  output: 'src/client',
});

openapi-ts.config.cjs

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

openapi-ts.config.mjs

/** @type {import('@hey-api/openapi-ts').UserConfig} */
export default {
  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.

Clients

By default, @hey-api/openapi-ts will generate a Fetch API client. If you want a different client, you can specify it using the client option.

fetch

export default {
  client: 'fetch',
  input: 'path/to/openapi.json',
  output: 'src/client',
}

fetch (beta)

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

axios

export default {
  client: 'axios',
  input: 'path/to/openapi.json',
  output: 'src/client',
}

angular

export default {
  client: 'angular',
  input: 'path/to/openapi.json',
  output: 'src/client',
}

node

export default {
  client: 'node',
  input: 'path/to/openapi.json',
  output: 'src/client',
}

xhr

export default {
  client: 'xhr',
  input: 'path/to/openapi.json',
  output: 'src/client',
}

We support these clients:

• angular (using RxJS)
• axios
• fetch

We also support the legacy Node.js and XHR clients:

• node (using node-fetch)
• xhr

Optionally, you can use client packages to avoid generating a new client on every run:

• fetch (beta)

TIP

You might not need a node client. Fetch API is experimental in Node.js v18 and stable in Node.js v21. We recommend upgrading to the latest Node.js version.

Formatting

By default, @hey-api/openapi-ts will not automatically format your client. To enable this feature, set output.format to a valid formatter.

disabled

export default {
  input: 'path/to/openapi.json',
  output: {
    format: false,
    path: 'src/client',
  },
}

prettier

export default {
  input: 'path/to/openapi.json',
  output: {
    format: 'prettier',
    path: 'src/client',
  },
}

biome

export default {
  input: 'path/to/openapi.json',
  output: {
    format: 'biome',
    path: 'src/client',
  },
}

You can also prevent your client from being processed by formatters by adding your output path to the tool's ignore file (e.g. .prettierignore).

Linting

For performance reasons, @hey-api/openapi-ts does not automatically lint your client. To enable this feature, set output.lint to a valid linter.

disabled

export default {
  input: 'path/to/openapi.json',
  output: {
    lint: false,
    path: 'src/client',
  },
}

eslint

export default {
  input: 'path/to/openapi.json',
  output: {
    lint: 'eslint',
    path: 'src/client',
  },
}

biome

export default {
  input: 'path/to/openapi.json',
  output: {
    lint: 'biome',
    path: 'src/client',
  },
}

You can also prevent your client from being processed by linters by adding your output path to the tool's ignore file (e.g. .eslintignore).

Enums

If you need to iterate through possible field values without manually typing arrays, you can export enums with

export default {
  input: 'path/to/openapi.json',
  output: 'src/client',
  types: {
    enums: 'javascript',
  },
}

This will export enums as plain JavaScript objects. For example, Foo would become

export const Foo = {
  FOO: 'foo',
  BAR: 'bar',
} as const;

We discourage generating TypeScript enums because they are not standard JavaScript and pose typing challenges. If you really need TypeScript enums, you can export them with

export default {
  input: 'path/to/openapi.json',
  output: 'src/client',
  types: {
    enums: 'typescript',
  },
}

JSON Schemas

By default, @hey-api/openapi-ts exports schemas from your OpenAPI specification as plain JavaScript objects. A great use case for schemas is client-side form input validation.

import { $Schema } from 'client/schemas';

const maxInputLength = $Schema.properties.text.maxLength;

if (userInput.length > maxInputLength) {
  throw new Error(`String length cannot exceed ${maxInputLength} characters!`);
}

If you're using OpenAPI v3.1, your schemas are JSON Schema compliant and can be used with other tools supporting JSON Schema. However, if you only want to validate form input, you don't want to include string descriptions inside your bundle. Instead, use form type.

export default {
  input: 'path/to/openapi.json',
  output: 'src/client',
  schemas: {
    type: 'form'
  },
}

If you don't need schemas at all, you can disable them with

export default {
  input: 'path/to/openapi.json',
  output: 'src/client',
  schemas: false,
}

Config API

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

Examples

You can view live examples on StackBlitz.