Migrating ​
While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code. If you run into a problem with migration, please open an issue.
@next ​
These changes haven't been released yet. However, you can migrate your code today to save time on migration once they're released.
Deprecated base
​
This config option is deprecated and will be removed in favor of clients.
Deprecated name
​
This config option is deprecated and will be removed in favor of clients.
Deprecated request
​
This config option is deprecated and will be removed in favor of clients.
Deprecated useOptions
​
This config option is deprecated and will be removed.
v0.58.0 ​
Removed schemas.gen.ts
re-export ​
index.ts
will no longer re-export schemas.gen.ts
to reduce the chance of producing broken output. Please update your code to import from schemas.gen.ts
directly.
import { mySchema } from 'client';
import { mySchema } from 'client/schemas.gen';
Removed transformers.gen.ts
re-export ​
index.ts
will no longer re-export transformers.gen.ts
to reduce the chance of producing broken output. Please update your code to import from transformers.gen.ts
directly.
import { myTransformer } from 'client';
import { myTransformer } from 'client/transformers.gen';
Added output.clean
option ​
By default, the output.path
folder will be emptied on every run. To preserve the previous behavior, set output.clean
to false
.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: {
clean: false,
path: 'src/client',
},
};
Added typescript.identifierCase
option ​
This change affects only the experimental parser. By default, the generated TypeScript interfaces will follow the PascalCase naming convention. In the previous versions, we tried to preserve the original name as much as possible. To keep the previous behavior, set typescript.identifierCase
to preserve
.
export default {
client: '@hey-api/client-fetch',
experimentalParser: true,
input: 'path/to/openapi.json',
output: 'src/client',
plugins: [
// ...other plugins
{
identifierCase: 'preserve',
name: '@hey-api/typescript',
},
],
};
v0.57.0 ​
Renamed @hey-api/services
plugin ​
This plugin has been renamed to @hey-api/sdk
.
Changed sdk.output
value ​
To align with the updated name, the @hey-api/sdk
plugin will generate an sdk.gen.ts
file. This will result in a breaking change if you're importing from services.gen.ts
. Please update your imports to reflect this change.
import { client } from 'client/services.gen';
import { client } from 'client/sdk.gen';
Renamed @hey-api/types
plugin ​
This plugin has been renamed to @hey-api/typescript
.
Added typescript.exportInlineEnums
option ​
By default, inline enums (enums not defined as reusable components in the input file) will be generated only as inlined union types. You can set exportInlineEnums
to true
to treat inline enums as reusable components. When true
, the exported enums will follow the style defined in enums
.
This is a breaking change since in the previous versions, inline enums were always treated as reusable components. To preserve your current output, set exportInlineEnums
to true
. This feature works only with the experimental parser.
export default {
client: '@hey-api/client-fetch',
experimentalParser: true,
input: 'path/to/openapi.json',
output: 'src/client',
plugins: [
// ...other plugins
{
exportInlineEnums: true,
name: '@hey-api/typescript',
},
],
};
v0.56.0 ​
Deprecated tree
in @hey-api/types
​
This config option is deprecated and will be removed when the experimental parser becomes the default.
v0.55.0 ​
This release adds the ability to filter your OpenAPI specification before it's processed. This feature will be useful if you are working with a large specification and are interested in generating output only from a small subset.
This feature is available only in the experimental parser. In the future, this will become the default parser. To opt-in to the experimental parser, set the experimentalParser
flag in your configuration to true
.
Deprecated include
in @hey-api/types
​
This config option is deprecated and will be removed when the experimental parser becomes the default.
Deprecated filter
in @hey-api/services
​
This config option is deprecated and will be removed when the experimental parser becomes the default.
Added input.include
option ​
This config option can be used to replace the deprecated options. It accepts a regular expression string matching against references within the bundled specification.
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.
v0.54.0 ​
This release makes plugins first-class citizens. In order to achieve that, the following breaking changes were introduced.
Removed CLI options ​
The --types
, --schemas
, and --services
CLI options have been removed. You can list which plugins you'd like to use explicitly by passing a list of plugins as --plugins <plugin1> <plugin2>
Removed *.export
option ​
Previously, you could explicitly disable export of certain artifacts using the *.export
option or its shorthand variant. These were both removed. You can now disable export of specific artifacts by manually defining an array of plugins
and excluding the unwanted plugin.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
schemas: false,
plugins: ['@hey-api/types', '@hey-api/services'],
};
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
schemas: {
export: false,
},
plugins: ['@hey-api/types', '@hey-api/services'],
};
Renamed schemas.name
option ​
Each plugin definition contains a name
field. This was conflicting with the schemas.name
option. As a result, it has been renamed to nameBuilder
.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
schemas: {
name: (name) => `${name}Schema`,
},
plugins: [
// ...other plugins
{
nameBuilder: (name) => `${name}Schema`,
name: '@hey-api/schemas',
},
],
};
Removed services.include
shorthand option ​
Previously, you could use a string value as a shorthand for the services.include
configuration option. You can now achieve the same result using the include
option.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
services: '^MySchema',
plugins: [
// ...other plugins
{
include: '^MySchema',
name: '@hey-api/services',
},
],
};
Renamed services.name
option ​
Each plugin definition contains a name
field. This was conflicting with the services.name
option. As a result, it has been renamed to serviceNameBuilder
.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
services: {
name: '{{name}}Service',
},
plugins: [
// ...other plugins
{
serviceNameBuilder: '{{name}}Service',
name: '@hey-api/services',
},
],
};
Renamed types.dates
option ​
Previously, you could set types.dates
to a boolean or a string value, depending on whether you wanted to transform only type strings into dates, or runtime code too. Many people found these options confusing, so they have been simplified to a boolean and extracted into a separate @hey-api/transformers
plugin.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
types: {
dates: 'types+transform',
},
plugins: [
// ...other plugins
{
dates: true,
name: '@hey-api/transformers',
},
],
};
Removed types.include
shorthand option ​
Previously, you could use a string value as a shorthand for the types.include
configuration option. You can now achieve the same result using the include
option.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
types: '^MySchema',
plugins: [
// ...other plugins
{
include: '^MySchema',
name: '@hey-api/types',
},
],
};
Renamed types.name
option ​
Each plugin definition contains a name
field. This was conflicting with the types.name
option. As a result, it has been renamed to style
.
export default {
client: '@hey-api/client-fetch',
input: 'path/to/openapi.json',
output: 'src/client',
types: {
name: 'PascalCase',
},
plugins: [
// ...other plugins
{
name: '@hey-api/types',
style: 'PascalCase',
},
],
};
v0.53.0 ​
Changed schemas name pattern ​
Previously, generated schemas would have their definition names prefixed with $
. This was problematic when using them with Svelte due to reserved keyword conflicts. The new naming pattern for schemas suffixes their definition names with Schema
. You can continue using the previous pattern by setting the schemas.name
configuration option.
export default {
input: 'path/to/openapi.json',
output: 'src/client',
schemas: {
name: (name) => `$${name}`,
},
};
Renamed legacy clients ​
Legacy clients were renamed to signal they are deprecated more clearly. To continue using legacy clients, you will need to update your configuration and prefix them with legacy/
.
export default {
client: 'fetch',
client: 'legacy/fetch',
input: 'path/to/openapi.json',
output: 'src/client',
};
export default {
client: 'axios',
client: 'legacy/axios',
input: 'path/to/openapi.json',
output: 'src/client',
};
export default {
client: 'angular',
client: 'legacy/angular',
input: 'path/to/openapi.json',
output: 'src/client',
};
export default {
client: 'node',
client: 'legacy/node',
input: 'path/to/openapi.json',
output: 'src/client',
};
export default {
client: 'xhr',
client: 'legacy/xhr',
input: 'path/to/openapi.json',
output: 'src/client',
};
v0.52.0 ​
Removed internal client
export ​
Previously, client packages would create a default client which you'd then import and configure.
import { client, createClient } from '@hey-api/client-fetch';
createClient({
baseUrl: 'https://example.com',
});
console.log(client.getConfig().baseUrl); // <-- 'https://example.com'
This client instance was used internally by services unless overridden. Apart from running createClient()
twice, people were confused about the meaning of global
configuration option.
Starting with v0.52.0, client packages will not create a default client. Instead, services will define their own client. You can now achieve the same configuration by importing client
from services and using the new setConfig()
method.
import { client } from 'client/services.gen';
client.setConfig({
baseUrl: 'https://example.com',
});
console.log(client.getConfig().baseUrl); // <-- 'https://example.com'
v0.51.0 ​
Required client
option ​
Client now has to be explicitly specified and @hey-api/openapi-ts
will no longer generate a legacy Fetch API client by default. To preserve the previous default behavior, set the client
option to fetch
.
export default {
client: 'fetch',
input: 'path/to/openapi.json',
output: 'src/client',
};
v0.48.0 ​
Changed methodNameBuilder()
signature ​
The services.methodNameBuilder()
function now provides a single operation
argument instead of multiple cherry-picked properties from it.
import { createClient } from '@hey-api/openapi-ts';
createClient({
input: 'path/to/openapi.json',
output: 'src/client',
services: {
methodNameBuilder: (service, name) => name,
methodNameBuilder: (operation) => operation.name,
},
});
v0.46.0 ​
Tree-shakeable services ​
By default, your services will now support tree-shaking. You can either use wildcard imports
import { DefaultService } from 'client/services.gen';
import * as DefaultService from 'client/services.gen';
DefaultService.foo(); // only import needs to be changed
or update all references to service classes
import { DefaultService } from 'client/services.gen';
import { foo } from 'client/services.gen';
foo(); // all references need to be changed
If you want to preserve the old behavior, you can set the newly exposed services.asClass
option to true.
export default {
input: 'path/to/openapi.json',
output: 'src/client',
services: {
asClass: true,
},
};
v0.45.0 ​
Removed client
inference ​
@hey-api/openapi-ts
will no longer infer which client you want to generate. By default, we will create a fetch
client. If you want a different client, you can specify it using the client
option.
export default {
client: 'axios',
input: 'path/to/openapi.json',
output: 'src/client',
};
v0.44.0 ​
Moved format
​
This config option has been moved. You can now configure formatter using the output.format
option.
export default {
format: 'prettier',
input: 'path/to/openapi.json',
output: {
format: 'prettier',
path: 'src/client',
},
};
Moved lint
​
This config option has been moved. You can now configure linter using the output.lint
option.
export default {
input: 'path/to/openapi.json',
lint: 'eslint',
output: {
lint: 'eslint',
path: 'src/client',
},
};
v0.43.0 ​
Removed enums.gen.ts
​
This file has been removed. Instead, enums are exported from types.gen.ts
. If you use imports from enums.gen.ts
, you should be able to easily find and replace all instances.
import { Foo } from 'client/enums.gen';
import { Foo } from 'client/types.gen';
Removed Enum
postfix ​
Generated enum names are no longer postfixed with Enum
. You can either alias your imports
import { FooEnum } from 'client/types.gen';
import { Foo as FooEnum } from 'client/types.gen';
console.log(FooEnum.value); // only import needs to be changed
or update all references to enums
import { FooEnum } from 'client/types.gen';
import { Foo } from 'client/types.gen';
console.log(Foo.value); // all references need to be changed
Moved enums
​
This config option has been moved. You can now configure enums using the types.enums
option.
export default {
enums: 'javascript',
input: 'path/to/openapi.json',
output: 'src/client',
types: {
enums: 'javascript',
},
};
v0.42.0 ​
Changed format
​
This config option has changed. You now need to specify a value (biome
or prettier
) to format the output (default: false
).
export default {
format: 'prettier',
input: 'path/to/openapi.json',
output: 'src/client',
}
Changed lint
​
This config option has changed. You now need to specify a value (biome
or eslint
) to lint the output (default: false
).
export default {
input: 'path/to/openapi.json',
lint: 'eslint',
output: 'src/client',
}
Moved operationId
​
This config option has been moved. You can now configure it using the services.operationId
option.
export default {
input: 'path/to/openapi.json',
output: 'src/client',
services: {
operationId: true,
},
}
v0.41.0 ​
Removed postfixServices
​
This config option has been removed. You can now transform service names using the string pattern parameter.
export default {
input: 'path/to/openapi.json',
output: 'src/client',
services: {
name: 'myAwesome{{name}}Api',
},
}
Removed serviceResponse
​
This config option has been removed. You can now configure service responses using the services.response
option.
export default {
input: 'path/to/openapi.json',
output: 'src/client',
services: {
response: 'body',
},
}
Removed useDateType
​
This config option has been removed. You can now configure date type using the types.dates
option.
export default {
input: 'path/to/openapi.json',
output: 'src/client',
type: {
dates: true,
},
}
v0.40.0 ​
Renamed models.gen.ts
file ​
models.gen.ts
is now called types.gen.ts
. If you use imports from models.gen.ts
, you should be able to easily find and replace all instances.
import type { Model } from 'client/models.gen'
import type { Model } from 'client/types.gen'
Renamed exportModels
​
This config option is now called types
.
PascalCase for types ​
You can now choose to export types using the PascalCase naming convention.
export default {
input: 'path/to/openapi.json',
output: 'src/client',
types: {
name: 'PascalCase',
},
}
Exported enums.gen.ts
file ​
Enums are now re-exported from the main index.ts
file.
v0.39.0 ​
Single enums.gen.ts
file ​
Enums are now exported from a separate file. If you use imports from models.ts
, you can change them to enums.gen.ts
.
import { Enum } from 'client/models';
import { Enum } from 'client/enums.gen';
Renamed models.ts
file ​
models.ts
is now called models.gen.ts
. If you use imports from models.ts
, you should be able to easily find and replace all instances.
import type { Model } from 'client/models'
import type { Model } from 'client/models.gen'
Renamed schemas.ts
file ​
schemas.ts
is now called schemas.gen.ts
. If you use imports from schemas.ts
, you should be able to easily find and replace all instances.
import { $Schema } from 'client/schemas';
import { $Schema } from 'client/schemas.gen';
Renamed services.ts
file ​
services.ts
is now called services.gen.ts
. If you use imports from services.ts
, you should be able to easily find and replace all instances.
import { DefaultService } from 'client/services';
import { DefaultService } from 'client/services.gen';
Deprecated exports from index.ts
​
Until this release, index.ts
file exported all generated artifacts. Starting from this release, enums are no longer exported from index.ts
. Models, schemas, and services will continue to be exported from index.ts
to avoid a huge migration lift, but we recommend migrating to import groups per artifact type.
import { Enum, type Model, $Schema, DefaultService } from 'client'
import { Enum } from 'client/enums.gen'
import type { Model } from 'client/models.gen'
import { $Schema } from 'client/schemas.gen'
import { DefaultService } from 'client/services.gen'
Prefer unknown
​
Types that cannot be determined will now be generated as unknown
instead of any
. To dismiss any errors, you can cast your variables back to any
, but we recommend updating your code to work with unknown
types.
const foo = bar as any
v0.38.0 ​
Renamed write
​
This config option is now called dryRun
(file) or --dry-run
(CLI). To restore existing functionality, invert the value, ie. write: true
is dryRun: false
and write: false
is dryRun: true
.
v0.36.0 ​
JSON Schema 2020-12 ​
Schemas are exported directly from OpenAPI specification. This means your schemas might change depending on which OpenAPI version you're using. If this release caused a field to be removed, consult the JSON Schema documentation on how to obtain the same value from JSON Schema (eg. required properties).
Renamed exportSchemas
​
This config option is now called schemas
.
v0.35.0 ​
Removed postfixModels
​
This config option has been removed.
v0.34.0 ​
Single services.ts
file ​
Services are now exported from a single file. If you used imports from individual service files, these will need to be updated to refer to the single services.ts
file.
v0.31.1 ​
Merged enums options ​
useLegacyEnums
config option is now enums: 'typescript'
and existing enums: true
option is now enums: 'javascript'
.
v0.31.0 ​
Single models.ts
file ​
TypeScript interfaces are now exported from a single file. If you used imports from individual model files, these will need to be updated to refer to the single models.ts
file.
Single schemas.ts
file ​
Schemas are now exported from a single file. If you used imports from individual schema files, these will need to be updated to refer to the single schemas.ts
file.
v0.27.38 ​
useOptions: true
​
By default, generated clients will use a single object argument to pass values to API calls. This is a significant change from the previous default of unspecified array of arguments. If migrating your application in one go isn't feasible, we recommend deprecating your old client and generating a new client.
import { DefaultService } from 'client/services'; // <-- old client with array arguments
import { DefaultService } from 'client_v2/services'; // <-- new client with options argument
This way, you can gradually switch over to the new syntax as you update parts of your code. Once you've removed all instances of client
imports, you can safely delete the old client
folder and find and replace all client_v2
calls to client
.
v0.27.36 ​
exportSchemas: true
​
By default, we will create schemas from your OpenAPI specification. Use exportSchemas: false
to preserve the old behavior.
v0.27.32 ​
Renamed Config
interface ​
This interface is now called UserConfig
.
v0.27.29 ​
Renamed openapi
CLI command ​
This command is now called openapi-ts
.
v0.27.26 ​
Removed indent
​
This config option has been removed. Use a code formatter to modify the generated files code style according to your preferences.
v0.27.24 ​
Removed useUnionTypes
​
This config option has been removed. Generated types will behave the same as useUnionTypes: true
before.
OpenAPI TypeScript Codegen ​
@hey-api/openapi-ts
was originally forked from Ferdi Koomen's openapi-typescript-codegen. Therefore, we want you to be able to migrate your projects. Migration should be relatively straightforward if you follow the release notes on this page. Start on v0.27.24 and scroll to the release you're migrating to.