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({
input: 'https://get.heyapi.dev/hey-api/backend',
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
});
/** @type {import('@hey-api/openapi-ts').UserConfig} */
module.exports = {
input: 'https://get.heyapi.dev/hey-api/backend',
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
/** @type {import('@hey-api/openapi-ts').UserConfig} */
export default {
input: 'https://get.heyapi.dev/hey-api/backend',
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
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 path, URL, or a string content resolving to an OpenAPI specification. Hey API supports all valid OpenAPI versions and file formats.
INFO
If you use an HTTPS URL with a self-signed certificate in development, you will need to set NODE_TLS_REJECT_UNAUTHORIZED=0
in your environment.
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.
Client ​
Clients are responsible for sending the actual HTTP requests. Using clients is not required, but you must add a client to plugins
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 and SDK 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.
Formatting ​
To format your output folder contents, set output.format
to a valid formatter.
export default {
input: 'https://get.heyapi.dev/hey-api/backend',
output: {
format: false,
path: 'src/client',
},
plugins: ['@hey-api/client-fetch'],
};
export default {
input: 'https://get.heyapi.dev/hey-api/backend',
output: {
format: 'prettier',
path: 'src/client',
},
plugins: ['@hey-api/client-fetch'],
};
export default {
input: 'https://get.heyapi.dev/hey-api/backend',
output: {
format: 'biome',
path: 'src/client',
},
plugins: ['@hey-api/client-fetch'],
};
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 {
input: 'https://get.heyapi.dev/hey-api/backend',
output: {
lint: false,
path: 'src/client',
},
plugins: ['@hey-api/client-fetch'],
};
export default {
input: 'https://get.heyapi.dev/hey-api/backend',
output: {
lint: 'eslint',
path: 'src/client',
},
plugins: ['@hey-api/client-fetch'],
};
export default {
input: 'https://get.heyapi.dev/hey-api/backend',
output: {
lint: 'biome',
path: 'src/client',
},
plugins: ['@hey-api/client-fetch'],
};
export default {
input: 'https://get.heyapi.dev/hey-api/backend',
output: {
lint: 'oxlint',
path: 'src/client',
},
plugins: ['@hey-api/client-fetch'],
};
You can also prevent your output from being linted by adding your output path to the linter's ignore file.
Filters ​
If you work with large specifications and want to generate output from their subset, you can use input.filters
to select the relevant resources.
Operations ​
Set include
to match operations to be included or exclude
to match operations to be excluded. Both exact keys and regular expressions are supported. When both rules match the same operation, exclude
takes precedence over include
.
export default {
input: {
filters: {
operations: {
include: ['GET /api/v1/foo', '/^[A-Z]+ /api/v1//'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
export default {
input: {
filters: {
operations: {
exclude: ['GET /api/v1/foo', '/^[A-Z]+ /api/v1//'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Tags ​
Set include
to match tags to be included or exclude
to match tags to be excluded. When both rules match the same tag, exclude
takes precedence over include
.
export default {
input: {
filters: {
tags: {
include: ['v2'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
export default {
input: {
filters: {
tags: {
exclude: ['v1'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Deprecated ​
You can filter out deprecated resources by setting deprecated
to false
.
export default {
input: {
filters: {
deprecated: false,
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Schemas ​
Set include
to match schemas to be included or exclude
to match schemas to be excluded. Both exact keys and regular expressions are supported. When both rules match the same schema, exclude
takes precedence over include
.
export default {
input: {
filters: {
schemas: {
include: ['Foo', '/^Bar/'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
export default {
input: {
filters: {
schemas: {
exclude: ['Foo', '/^Bar/'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Parameters ​
Set include
to match parameters to be included or exclude
to match parameters to be excluded. Both exact keys and regular expressions are supported. When both rules match the same parameter, exclude
takes precedence over include
.
export default {
input: {
filters: {
parameters: {
include: ['QueryParameter', '/^MyQueryParameter/'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
export default {
input: {
filters: {
parameters: {
exclude: ['QueryParameter', '/^MyQueryParameter/'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Request Bodies ​
Set include
to match request bodies to be included or exclude
to match request bodies to be excluded. Both exact keys and regular expressions are supported. When both rules match the same request body, exclude
takes precedence over include
.
export default {
input: {
filters: {
requestBodies: {
include: ['Payload', '/^SpecialPayload/'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
export default {
input: {
filters: {
requestBodies: {
exclude: ['Payload', '/^SpecialPayload/'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Responses ​
Set include
to match responses to be included or exclude
to match responses to be excluded. Both exact keys and regular expressions are supported. When both rules match the same response, exclude
takes precedence over include
.
export default {
input: {
filters: {
responses: {
include: ['Foo', '/^Bar/'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
export default {
input: {
filters: {
responses: {
exclude: ['Foo', '/^Bar/'],
},
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Orphaned resources ​
If you only want to exclude orphaned resources, set orphans
to false
. This is the default value when combined with any other filters. If this isn't the desired behavior, you may want to set orphans
to true
to always preserve unused resources.
export default {
input: {
filters: {
orphans: false,
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Order ​
For performance reasons, we don't preserve the original order when filtering out resources. If maintaining the original order is important to you, set preserveOrder
to true
.
export default {
input: {
filters: {
preserveOrder: true,
},
path: 'https://get.heyapi.dev/hey-api/backend',
},
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
};
Watch Mode ​
WARNING
Watch mode currently supports only remote files via URL.
If your schema changes frequently, you may want to automatically regenerate the output during development. To watch your input file for changes, enable watch
mode in your configuration or pass the --watch
flag to the CLI.
export default {
input: 'https://get.heyapi.dev/hey-api/backend',
output: 'src/client',
plugins: ['@hey-api/client-fetch'],
watch: true,
};
npx @hey-api/openapi-ts \
-i https://get.heyapi.dev/hey-api/backend \
-o src/client \
-c @hey-api/client-fetch \
-w
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 {
input: 'https://get.heyapi.dev/hey-api/backend',
output: {
clean: false,
path: 'src/client',
},
plugins: ['@hey-api/client-fetch'],
};
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.
Sponsors ​
Love Hey API? Become our sponsor.