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.
import { defineConfig } from '@hey-api/openapi-ts';
export default defineConfig({
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
});
/** @type {import('@hey-api/openapi-ts').UserConfig} */
module.exports = {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
};
/** @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.
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.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: {
format: false,
path: 'src/client',
},
};
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: {
format: 'prettier',
path: 'src/client',
},
};
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.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: {
lint: false,
path: 'src/client',
},
};
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: {
lint: 'eslint',
path: 'src/client',
},
};
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: {
lint: 'biome',
path: 'src/client',
},
};
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: {
lint: 'oxlint',
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 SDKs (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, an SDK, and JSON Schemas 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
.
export default {
client: '@hey-api/client-fetch',
experimentalParser: true,
input: 'path/to/openapi.json',
output: 'src/client',
};
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 be used with the legacy clients regardless of the experimentalParser
flag value. However, it's unlikely to receive any further updates.
Filters ​
WARNING
To use this feature, you must opt in to the experimental parser.
If you work with large specifications and want to generate output from their subset, you can use regular expressions to select the relevant definitions. Set input.include
to match resource references to be included or input.exclude
to match resource references to be excluded. When both regular expressions match the same definition, input.exclude
takes precedence over input.include
.
export default {
client: '@hey-api/client-fetch',
experimentalParser: true,
input: {
// match only the schema named `foo` and `GET` operation for the `/api/v1/foo` path
include: '^(#/components/schemas/foo|#/paths/api/v1/foo/get)$',
path: 'path/to/openapi.json',
},
output: 'src/client',
};
export default {
client: '@hey-api/client-fetch',
experimentalParser: true,
input: {
// match everything except for the schema named `foo` and `GET` operation for the `/api/v1/foo` path
exclude: '^(#/components/schemas/foo|#/paths/api/v1/foo/get)$',
path: 'path/to/openapi.json',
},
output: 'src/client',
};
Custom Files ​
By default, you can't keep custom files in the output.path
folder because it's emptied on every run. If you're sure you need to disable this behavior, set output.clean
to false
.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: {
clean: false,
path: 'src/client',
},
};
WARNING
Setting output.clean
to false
may result in broken output. Ensure you typecheck your code.
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.