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({
  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.

Clients

Clients are responsible for sending the actual HTTP requests. Apart from input and output, this is the only required option.

You can learn more on the Clients page.

Services

Services are abstractions on top of clients and serve the same purpose. By default, @hey-api/openapi-ts will generate a flat service layer. Your choice to use services comes down to personal preferences and bundle size considerations.

You can learn more on the Output page.

Enums

By default, @hey-api/openapi-ts will only emit enums as types. You may want to generate runtime artifacts. A good use case is iterating through possible field values without manually typing arrays. To emit runtime enums, set types.enums to a valid option.

disabled

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

javascript

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

typescript

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

We recommend exporting enums as plain JavaScript objects. TypeScript enums are not a type-level extension of JavaScript and pose typing challenges.

JSON Schemas

By default, @hey-api/openapi-ts generates schemas from your OpenAPI specification. A great use case for schemas is client-side form input validation. If you're using OpenAPI 3.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 probably don't want to include string descriptions inside your bundle. You can choose your preferred type using schemas.type option.

json

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

form

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

disabled

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

Formatting

By default, @hey-api/openapi-ts will not automatically format your output. To enable this feature, 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

By default, @hey-api/openapi-ts will not automatically lint your output. To enable this feature, 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.

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.