openapi-ts Documentation

Get API Copy Chapter

As you can deduce from the examples above, the default command for fetching OpenAPI specifications looks like this.

https://get.heyapi.dev/<organization>/<project>

If you created an organization foo with project bar earlier, your URL would look like this.

https://get.heyapi.dev/foo/bar

Auth Copy Section

Projects are private by default, you will need to be authenticated to download OpenAPI specifications. We recommend using project API keys in CI workflows and personal API keys for local development.

Once you have your API key, you can authenticate the request using the Authorization header or api_key query parameter.

https://get.heyapi.dev/foo/bar?api_key=<my_api_key>

Congratulations on fetching your first OpenAPI specification! 🎉

Filters Copy Section

The default behavior returns the last uploaded specification. This might not be what you want. You can use a range of filters to narrow down the possible specifications, or pin your builds to an exact version.

`branch`

You can fetch the last build from branch by providing the branch query parameter.

https://get.heyapi.dev/foo/bar?branch=production

`commit_sha`

You can fetch an exact specification by providing the commit_sha query parameter. This will always return the same file.

https://get.heyapi.dev/foo/bar?commit_sha=0eb34c2024841ce95620f3ec02a2fea164ea4e9d

`tags`

If you're tagging your specifications with custom tags, you can use them to filter the results. When you provide multiple tags, only the first match will be returned.

https://get.heyapi.dev/foo/bar?tags=optional,custom,tags

`version`

Every OpenAPI document contains a required version field. You can use this value to fetch the last uploaded specification matching the value.

https://get.heyapi.dev/foo/bar?version=1.0.0

Feedback Copy Chapter

We'd love your feedback! You can contact us on social media (search Hey API), email, or GitHub.

Pricing Copy Chapter

The platform is currently in beta with our focus being on delivering a great experience. We plan to announce pricing once we have gathered enough data around usage patterns. However, we can guarantee there will always be a free plan available. Our mission to bring the finest tooling for working with APIs remains unchanged.

Web Src Content Docs Docs Openapi Typescript License (`web/src/content/docs/docs/openapi/typescript/license.md`) Copy Section

title: License Copy Chapter

License

MIT License Copy Section

Copyright (c) 2026-present Hey API

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Web Src Content Docs Docs Openapi Typescript Migrating (`web/src/content/docs/docs/openapi/typescript/migrating.mdx`) Copy Section

title: Migrating Copy Chapter

import { Tabs, TabItem } from '@astrojs/starlight/components';

Migrating

Hey API is in active development, which allows us to move quickly and continuously improve the project. That pace sometimes comes with breaking changes. This page documents those changes and provides migration guidance for each release. If you need help with a migration, please open an issue.

v0.99.0 Copy Chapter

Plugin duplicates behavior Copy Section

If you specified the same plugin multiple times, only the last instance would be used. We eventually added a warning for this behavior, but that didn't treat the root issue. This release changes that by merging duplicate plugin configurations.

Renamed `plugin.symbols` to `plugin.imports` Copy Section

To better represent its functionality, the plugin.symbols property has been renamed to plugin.imports.

Removed `plugin.external()` function Copy Section

This function was used to reference external symbols. All plugins now use the Imports API, which allows you to reference external symbols in a type-safe way through plugin.imports.

Removed `plugin.registerSymbol()` function Copy Section

This function was an alias for plugin.symbol() accepting a single argument. It has been removed in favor of plugin.symbol() which can now also accept a single argument.

v0.98.0 Copy Chapter

Declarative configuration Copy Section

This is an internal change that simplifies the configuration and plugin APIs. The generated output should be unaffected, please open an issue if that's not the case. If you have custom plugins, refer to the custom plugin guide for the latest instructions.

v0.97.0 Copy Chapter

Changed `runtimeConfigPath` behavior Copy Section

This was a known, long-standing issue confusing first-time users. Before, defining client runtimeConfigPath value would paste it verbatim to the generated output. This release changes the behavior to resolve relative to the output folder.

Changed Ky client behavior Copy Section

The Ky client was updated to be more intuitive. Some Ky options now need to be passed via the kyOptions field and you need to pass undefined to unset an option.

Changed error interceptors behavior Copy Section

Error interceptors now receive the result of the previous error interceptor. This aligns their behavior with request and response interceptors. This change only affects you if you use multiple interceptors.

Optional client request and response Copy Section

The returned request and response objects are now typed as optional. This aligns the types with the actual runtime behavior, which remains unchanged.

Respect `throwOnError` option Copy Section

Previously, there were instances where setting throwOnError to false would still throw an error. This most commonly happened when request validation failed. With this change, throwOnError is now truly respected.

v0.96.0 Copy Chapter

Removed Node 20 support Copy Section

This release bumps the minimum required Node version to 22.13.

v0.95.0 Copy Chapter

Validator request schemas Copy Section

Valibot and Zod plugins no longer export composite request Data schemas. Instead, each layer is exported as a separate schema. If you're using validators with SDKs, you can preserve the composite schema with shouldExtract:

Removed `plugin.getSymbol()` function Copy Section

This function has been removed. You can use plugin.querySymbol() instead. It accepts the same arguments and returns the same result.

v0.93.0 Copy Chapter

Removed resolver node Copy Section

Valibot and Zod plugins no longer expose the enum.nodes.nullable node. Both plugins were refactored so that nullable values are handled outside of resolvers.

v0.92.0 Copy Chapter

Updated Symbol interface Copy Section

The exportFrom property has been replaced with the getExportFromFilePath() function. This allows you to dynamically determine export paths based on symbol properties. This is a low-level feature, so you're most likely unaffected.

v0.91.0 Copy Chapter

Removed CommonJS (CJS) support Copy Section

@hey-api/openapi-ts is now ESM-only. This change simplifies the codebase, improves tree-shaking, and enables better integration with modern bundlers and TypeScript tooling.

CommonJS entry points (require(), module.exports) are no longer supported. If you are in a CJS environment, you can still load the package dynamically using import() like:

const { defineConfig } = await import('@hey-api/openapi-ts');

If you have previously written:

const { defineConfig } = require('@hey-api/openapi-ts');

Migrate by updating your static imports:

import { defineConfig } from '@hey-api/openapi-ts';

If your environment cannot use ESM, pin to a previous version.

v0.90.0 Copy Chapter

Resolvers API Copy Section

The Resolvers API has been simplified and expanded to provide a more consistent behavior across plugins. You can view a few common examples on the Resolvers page.

Structure API Copy Section

The SDK plugin and Angular plugin now implement the Structure API, enabling more complex structures and fixing several known issues.

Some Structure APIs are incompatible with the previous configuration, most notably the methodNameBuilder function, which accepted the operation object as an argument. You can read the SDK Output section to familiarize yourself with the Structure API.

Please open an issue if you're unable to migrate your configuration to the new syntax.

v0.89.0 Copy Chapter

Prefer named exports Copy Section

This release changes the default for index.ts to prefer named exports. Named exports may lead to better IDE and bundler performance compared to asterisk (*) as your tooling doesn't have to inspect the underlying module to discover exports.

While this change is merely cosmetic, you can set output.preferExportAll to true if you prefer to use the asterisk.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    path: 'src/client',
    preferExportAll: true,
  },
};

Removed `symbol:setValue:*` events Copy Section

These events have been removed in favor of node:set:* events.

v0.88.0 Copy Chapter

Removed `compiler` and `tsc` exports Copy Section

This release removes the compiler utility functions. Instead, it introduces a new TypeScript DSL exposed under the $ symbol. All plugins now use this interface, so you may notice slight changes in the generated output.

v0.87.0 Copy Chapter

Removed legacy clients Copy Section

This release removes support for legacy clients and plugins. Please migrate to the new clients if you haven't done so yet. If you're unable to do so due to a missing feature, let us know on GitHub.

v0.86.0 Copy Chapter

Removed Node 18 support Copy Section

This release bumps the minimum required Node version to 20.19.

v0.85.0 Copy Chapter

Updated `output` options Copy Section

We made the output configuration more consistent by using null to represent disabled options. This change does not affect boolean options.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    format: false,
    format: null,
    lint: false,
    lint: null,
    path: 'src/client',
    tsConfigPath: 'off',
    tsConfigPath: null,
  },
};

Updated Pinia Colada query options Copy Section

Pinia Colada query options now use defineQueryOptions to improve reactivity support. Instead of calling the query options function, you can use one of the following approaches.

</TabItem>
  <TabItem label="properties">
```ts title="colada.gen.ts"
const petId = ref<number | null>(1);

useQuery(() => ({
  ...getPetByIdQuery({
    path: { petId: petId.value as number },
  }),
  enabled: () => petId.value !== null,
}));

v0.84.0 Copy Chapter

Symbol API Copy Section

This release improves the Symbol API, which adds the capability to place symbols in arbitrary files. We preserved the previous output structure for all plugins except Angular.

You can preserve the previous Angular output by writing your own placement function.

TypeScript renderer Copy Section

We ship a dedicated TypeScript renderer for .ts files. This release improves the renderer's ability to group and sort imported modules, resulting in a more polished output.

Removed `output` plugin option Copy Section

Due to the Symbol API release, this option has been removed from the Plugin API.

v0.83.0 Copy Chapter

Symbol API Copy Section

This release adds the Symbol API, which significantly reduces the risk of naming collisions. While the generated output should only include formatting changes, this feature introduces breaking changes to the Plugin API that affect custom plugins.

We will update the custom plugin guide once the Plugin API becomes more stable.

Removed `groupByTag` Pinia Colada option Copy Section

This option has been removed to provide a more consistent API across plugins. We plan to bring it back in a future release.

v0.82.0 Copy Chapter

Hooks API Copy Section

This release adds the Hooks API, giving you granular control over which operations generate queries and mutations. As a result, we tightened the previous behavior and POST operations no longer generate queries by default. To preserve the old behavior, add a custom matcher.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    hooks: {
      operations: {
        isQuery: (op) => (op.method === 'post' ? true : undefined),
      },
    },
  },
};

v0.81.0 Copy Chapter

Server-Sent Events (SSE) Copy Section

This release adds support for server-sent events (SSE). Instead of treating text/event-stream content types as regular HTTP methods, we now generate SSE streams. In practice, you will want to update your affected endpoints to process streamed events.

v0.80.0 Copy Chapter

Added Zod 4 and Zod Mini Copy Section

This release adds support for Zod 4 and Zod Mini. By default, the zod plugin will generate output for Zod 4. If you want to preserve the previous output for Zod 3 or use Zod Mini, set compatibilityVersion to 3 or mini.

v0.79.0 Copy Chapter

Removed `typescript+namespace` enums mode Copy Section

Due to a simpler TypeScript plugin implementation, the typescript+namespace enums mode is no longer necessary. This mode was used in the past to group inline enums under the same namespace. With the latest changes, this behavior is no longer supported. You can either choose to ignore inline enums (default), or use the enums transform (added in v0.78.0) to convert them into reusable components which will get exported as usual.

v0.78.0 Copy Chapter

Added `parser` options Copy Section

Previously, @hey-api/typescript would generate correct types, but the validator plugins would have to re-implement the same logic or generate schemas that didn't match the generated types.

Since neither option was ideal, this release adds a dedicated place for parser options. Parser is responsible for preparing the input so plugins can generate more accurate output with less effort.

You can learn more about configuring parser on the Parser page.

Moved `input` options Copy Section

The following options were moved to the new parser group.

• input.filters moved to parser.filters
• input.pagination moved to parser.pagination
• input.patch moved to parser.patch
• input.validate_EXPERIMENTAL moved to parser.validate_EXPERIMENTAL

Updated `typescript` options Copy Section

The following options were renamed.

• enumsCase moved to enums.case
• enumsConstantsIgnoreNull moved to enums.constantsIgnoreNull

Moved `typescript` options Copy Section

The following options were moved to the new parser group.

• exportInlineEnums moved to parser.transforms.enums
• readOnlyWriteOnlyBehavior moved to parser.transforms.readWrite.enabled
• readableNameBuilder moved to parser.transforms.readWrite.responses.name
• writableNameBuilder moved to parser.transforms.readWrite.requests.name

Updated `readWrite.responses` name Copy Section

Additionally, the naming pattern for response schemas has changed from {name}Readable to {name}. This is to prevent your code from breaking by default when using a schema that gets updated with a write-only field.

v0.77.0 Copy Chapter

Updated `sdk.validator` option Copy Section

Clients can now validate both request and response data. As a result, passing a boolean or string to validator will control both of these options. To preserve the previous behavior, set validator.request to false and validator.response to your previous configuration.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@hey-api/sdk',
      validator: true,
      validator: {
        request: false,
        response: true,
      },
    },
  ],
};

Updated Plugin API Copy Section

Please refer to the custom plugin tutorial for the latest guide.

v0.76.0 Copy Chapter

Single Valibot schema per request Copy Section

Previously, we generated a separate schema for each endpoint parameter and request body. In v0.76.0, a single request schema is generated for the whole endpoint. It may contain a request body, parameters, and headers.

const vData = v.object({
  body: v.optional(
    v.object({
      foo: v.optional(v.string()),
      bar: v.optional(v.union([v.number(), v.null()])),
    }),
  ),
  headers: v.optional(v.never()),
  path: v.object({
    baz: v.string(),
  }),
  query: v.optional(v.never()),
});

If you need to access individual fields, you can do so using the .entries API. For example, we can get the request body schema with vData.entries.body.

v0.75.0 Copy Chapter

Updated TanStack Query options Copy Section

The TanStack Query plugin options have been expanded to support more naming and casing patterns. As a result, the following options have been renamed.

• queryOptionsNameBuilder renamed to queryOptions
• infiniteQueryOptionsNameBuilder renamed to infiniteQueryOptions
• mutationOptionsNameBuilder renamed to mutationOptions
• queryKeyNameBuilder renamed to queryKeys
• infiniteQueryKeyNameBuilder renamed to infiniteQueryKeys

Added `plugin.forEach()` method Copy Section

This method replaces the .subscribe() method. Additionally, .forEach() is executed immediately, which means we don't need the before and after events – simply move your code before and after the .forEach() block.

plugin.subscribe('operation', (event) => {
  // do something with event
});
plugin.subscribe('schema', (event) => {
plugin.forEach('operation', 'schema', (event) => {
  // do something with event
});

v0.74.0 Copy Chapter

Single Zod schema per request Copy Section

Previously, we generated a separate schema for each endpoint parameter and request body. In v0.74.0, a single request schema is generated for the whole endpoint. It may contain a request body, parameters, and headers.

const zData = z.object({
  body: z
    .object({
      foo: z.string().optional(),
      bar: z.union([z.number(), z.null()]).optional(),
    })
    .optional(),
  headers: z.never().optional(),
  path: z.object({
    baz: z.string(),
  }),
  query: z.never().optional(),
});

If you need to access individual fields, you can do so using the .shape API. For example, we can get the request body schema with zData.shape.body.

v0.73.0 Copy Chapter

Bundle `@hey-api/client-*` plugins Copy Section

In previous releases, you had to install a separate client package to generate a fully working output, e.g., npm install @hey-api/client-fetch. This created a few challenges: getting started was slower, upgrading was sometimes painful, and bundling too. Beginning with v0.73.0, all Hey API clients are bundled by default and don't require installing any additional dependencies. You can remove any installed client packages and re-run @hey-api/openapi-ts.

npm uninstall @hey-api/client-fetch

v0.72.0 Copy Chapter

Added `sdk.classStructure` option Copy Section

When generating class-based SDKs, we now try to infer the ideal structure using operationId keywords. If you'd like to preserve the previous behavior, set classStructure to off.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      classStructure: 'off',
      name: '@hey-api/sdk',
    },
  ],
};

v0.71.0 Copy Chapter

Renamed `sdk.serviceNameBuilder` option Copy Section

This option has been renamed to sdk.classNameBuilder to better represent its functionality. Additionally, it's no longer set by default. To preserve the previous behavior, update your configuration.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      classNameBuilder: '{{name}}Service',
      name: '@hey-api/sdk',
      serviceNameBuilder: '{{name}}Service',
    },
  ],
};

v0.68.0 Copy Chapter

Upgraded input filters Copy Section

Input filters now avoid generating invalid output without requiring you to specify every missing schema as in the previous releases. As part of this release, we changed the way filters are configured and removed the support for regular expressions. Let us know if regular expressions are still useful for you and want to bring them back!

v0.67.0 Copy Chapter

Respecting `moduleResolution` value in `tsconfig.json` Copy Section

This release introduces functionality related to your tsconfig.json file. The initial feature properly respects the value of your moduleResolution field. If you're using nodenext, the relative module paths in your output will be appended with .js. To preserve the previous behavior where we never appended .js to relative module paths, set output.tsConfigPath to off.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    path: 'src/client',
    tsConfigPath: 'off',
  },
};

v0.66.0 Copy Chapter

Read-only and write-only fields Copy Section

Starting with v0.66.0, @hey-api/typescript will generate separate types for payloads and responses if it detects any read-only or write-only fields. To preserve the previous behavior and generate a single type regardless, set readOnlyWriteOnlyBehavior to off.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@hey-api/typescript',
      readOnlyWriteOnlyBehavior: 'off',
    },
  ],
};

v0.64.0 Copy Chapter

Added `ClientOptions` interface Copy Section

The Config interface now accepts an optional generic extending ClientOptions instead of boolean type ThrowOnError.

type Foo = Config<false>;
type Foo = Config<{ throwOnError: false }>;

Added `client.baseUrl` option Copy Section

You can use this option to configure the default base URL for the generated client. By default, we will attempt to resolve the first defined server or infer the base URL from the input path. If you'd like to preserve the previous behavior, set baseUrl to false.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      baseUrl: false,
      name: '@hey-api/client-fetch',
    },
  ],
};

v0.63.0 Copy Chapter

Client plugins Copy Section

Clients are now plugins generating their own client.gen.ts file. There's no migration needed if you're using CLI. If you're using the configuration file, move client options to plugins.

export default {
  client: '@hey-api/client-fetch',
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: ['@hey-api/client-fetch'],
};

Added `client.gen.ts` file Copy Section

Related to above, the internal client instance previously located in sdk.gen.ts is now defined in client.gen.ts. If you're importing it in your code, update the import module.

import { client } from 'client/sdk.gen';
import { client } from 'client/client.gen';

Moved `sdk.throwOnError` option Copy Section

This SDK configuration option has been moved to the client plugins where applicable. Not every client can be configured to throw on error, so it didn't make sense to expose the option when it didn't have any effect.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-fetch',
      throwOnError: true,
    },
    {
      name: '@hey-api/sdk',
      throwOnError: true,
    },
  ],
};

v0.62.0 Copy Chapter

Changed parser Copy Section

Formerly known as the experimental parser, this is now the default parser. This change should not impact the generated output's functionality. However, there might be cases where this results in breaking changes due to different handling of certain scenarios. If you need to revert to the legacy parser, set the experimentalParser flag to false.

export default {
  client: '@hey-api/client-fetch',
  experimentalParser: false,
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
};

Note that the legacy parser is no longer supported and will be removed in the v1 release.

v0.61.0 Copy Chapter

Added `auth` option Copy Section

Client package functions accessToken and apiKey were replaced with a single auth function for fetching auth tokens. If your API supports multiple auth mechanisms, you can use the auth argument to return the appropriate token.

import { client } from 'client/sdk.gen';

client.setConfig({
  accessToken: () => '<my_token>',
  apiKey: () => '<my_token>',
  auth: (auth) => '<my_token>',
});

Due to conflict with the Axios native auth option, we removed support for configuring Axios auth. Please let us know if you require this feature added back.

Added `watch` option Copy Section

While this is a new feature, supporting it involved replacing the @apidevtools/json-schema-ref-parser dependency with our own implementation. Since this was a big change, we're applying caution and marking this as a breaking change.

Changed `parseAs: 'auto'` behavior Copy Section

The Fetch API client will return raw response body as ReadableStream when Content-Type response header is undefined and parseAs is auto.

v0.60.0 Copy Chapter

Added `sdk.transformer` option Copy Section

When generating SDKs, you now have to specify transformer in order to modify response data. By default, adding @hey-api/transformers to your plugins will only produce additional output. To preserve the previous functionality, set sdk.transformer to true.

export default {
  client: '@hey-api/client-fetch',
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      dates: true,
      name: '@hey-api/transformers',
    },
    {
      name: '@hey-api/sdk',
      transformer: true,
    },
  ],
};

v0.59.0 Copy Chapter

Added `logs.level` option Copy Section

You can now configure different log levels. As part of this feature, we had to introduce a breaking change by moving the debug option to logs.level. This will affect you if you're calling @hey-api/openapi-ts from Node.js (not CLI) or using the configuration file.

export default {
  client: '@hey-api/client-fetch',
  debug: true,
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  logs: {
    level: 'debug',
  },
  output: 'src/client',
};

Updated default `plugins` Copy Section

@hey-api/schemas has been removed from the default plugins. To continue using it, add it to your plugins array.

export default {
  client: '@hey-api/client-fetch',
  experimentalParser: true,
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    '@hey-api/schemas',
  ],
};

v0.58.0 Copy Chapter

Removed `schemas.gen.ts` re-export Copy Section

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 Copy Section

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 Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    clean: false,
    path: 'src/client',
  },
};

Added `typescript.identifierCase` option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      identifierCase: 'preserve',
      name: '@hey-api/typescript',
    },
  ],
};

v0.57.0 Copy Chapter

Renamed `@hey-api/services` plugin Copy Section

This plugin has been renamed to @hey-api/sdk.

Changed `sdk.output` value Copy Section

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 Copy Section

This plugin has been renamed to @hey-api/typescript.

Added `typescript.exportInlineEnums` option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      exportInlineEnums: true,
      name: '@hey-api/typescript',
    },
  ],
};

v0.56.0 Copy Chapter

Deprecated `tree` in `@hey-api/types` Copy Section

This config option is deprecated and will be removed when the experimental parser becomes the default.

v0.55.0 Copy Chapter

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` Copy Section

This config option is deprecated and will be removed when the experimental parser becomes the default.

Deprecated `filter` in `@hey-api/services` Copy Section

This config option is deprecated and will be removed when the experimental parser becomes the default.

Added `input.include` option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  },
  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 Copy Chapter

This release makes plugins first-class citizens. In order to achieve that, the following breaking changes were introduced.

Removed CLI options Copy Section

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

Removed `*.export` option Copy Section

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.

Renamed `schemas.name` option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  schemas: {
    name: (name) => `${name}Schema`,
  },
  plugins: [
    // ...other plugins
    {
      nameBuilder: (name) => `${name}Schema`,
      name: '@hey-api/schemas',
    },
  ],
};

Removed `services.include` shorthand option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  services: '^MySchema',
  plugins: [
    // ...other plugins
    {
      include: '^MySchema',
      name: '@hey-api/services',
    },
  ],
};

Renamed `services.name` option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  services: {
    name: '{{name}}Service',
  },
  plugins: [
    // ...other plugins
    {
      serviceNameBuilder: '{{name}}Service',
      name: '@hey-api/services',
    },
  ],
};

Renamed `types.dates` option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  types: {
    dates: 'types+transform',
  },
  plugins: [
    // ...other plugins
    {
      dates: true,
      name: '@hey-api/transformers',
    },
  ],
};

Removed `types.include` shorthand option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  types: '^MySchema',
  plugins: [
    // ...other plugins
    {
      include: '^MySchema',
      name: '@hey-api/types',
    },
  ],
};

Renamed `types.name` option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  types: {
    name: 'PascalCase',
  },
  plugins: [
    // ...other plugins
    {
      name: '@hey-api/types',
      style: 'PascalCase',
    },
  ],
};

v0.53.0 Copy Chapter

Changed schemas name pattern Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  schemas: {
    name: (name) => `$${name}`,
  },
};

Renamed legacy clients Copy Section

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/.

v0.52.0 Copy Chapter

Removed internal `client` export Copy Section

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 Copy Chapter

Required `client` option Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
};

v0.48.0 Copy Chapter

Changed `methodNameBuilder()` signature Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  services: {
    methodNameBuilder: (service, name) => name,
    methodNameBuilder: (operation) => operation.name,
  },
});

v0.46.0 Copy Chapter

Tree-shakeable services Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  services: {
    asClass: true,
  },
};

v0.45.0 Copy Chapter

Removed `client` inference Copy Section

@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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
};

v0.44.0 Copy Chapter

Moved `format` Copy Section

This config option has been moved. You can now configure formatter using the output.format option.

export default {
  format: 'prettier',
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    format: 'prettier',
    path: 'src/client',
  },
};

Moved `lint` Copy Section

This config option has been moved. You can now configure linter using the output.lint option.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  lint: 'eslint',
  output: {
    lint: 'eslint',
    path: 'src/client',
  },
};

v0.43.0 Copy Chapter

Removed `enums.gen.ts` Copy Section

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 Copy Section

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` Copy Section

This config option has been moved. You can now configure enums using the types.enums option.

export default {
  enums: 'javascript',
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  types: {
    enums: 'javascript',
  },
};

v0.42.0 Copy Chapter

Changed `format` Copy Section

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: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
}

Changed `lint` Copy Section

This config option has changed. You now need to specify a value (biome or eslint) to lint the output (default: false).

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  lint: 'eslint',
  output: 'src/client',
}

Moved `operationId` Copy Section

This config option has been moved. You can now configure it using the services.operationId option.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  services: {
    operationId: true,
  },
}

v0.41.0 Copy Chapter

Removed `postfixServices` Copy Section

This config option has been removed. You can now transform service names using the string pattern parameter.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  services: {
    name: 'myAwesome{{name}}Api',
  },
}

Removed `serviceResponse` Copy Section

This config option has been removed. You can now configure service responses using the services.response option.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  services: {
    response: 'body',
  },
}

Removed `useDateType` Copy Section

This config option has been removed. You can now configure date type using the types.dates option.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  type: {
    dates: true,
  },
}

v0.40.0 Copy Chapter

Renamed `models.gen.ts` file Copy Section

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` Copy Section

This config option is now called types.

PascalCase for types Copy Section

You can now choose to export types using the PascalCase naming convention.

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  types: {
    name: 'PascalCase',
  },
}

Exported `enums.gen.ts` file Copy Section

Enums are now re-exported from the main index.ts file.

v0.39.0 Copy Chapter

Single `enums.gen.ts` file Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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` Copy Section

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` Copy Section

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 Copy Chapter

Renamed `write` Copy Section

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 Copy Chapter

JSON Schema 2020-12 Copy Section

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 (e.g., required properties).

Renamed `exportSchemas` Copy Section

This config option is now called schemas.

v0.35.0 Copy Chapter

Removed `postfixModels` Copy Section

This config option has been removed.

v0.34.0 Copy Chapter

Single `services.ts` file Copy Section

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 Copy Chapter

Merged enums options Copy Section

useLegacyEnums config option is now enums: 'typescript' and existing enums: true option is now enums: 'javascript'.

v0.31.0 Copy Chapter

Single `models.ts` file Copy Section

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 Copy Section

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 Copy Chapter

`useOptions: true` Copy Section

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 Copy Chapter

`exportSchemas: true` Copy Section

By default, we will create schemas from your OpenAPI specification. Use exportSchemas: false to preserve the old behavior.

v0.27.32 Copy Chapter

Renamed `Config` interface Copy Section

This interface is now called UserConfig.

v0.27.29 Copy Chapter

Renamed `openapi` CLI command Copy Section

This command is now called openapi-ts.

v0.27.26 Copy Chapter

Removed `indent` Copy Section

This config option has been removed. Use a code formatter to modify the generated files code style according to your preferences.

v0.27.24 Copy Chapter

Removed `useUnionTypes` Copy Section

This config option has been removed. Generated types will behave the same as useUnionTypes: true before.

OpenAPI TypeScript Codegen Copy Chapter

@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.

Web Src Content Docs Docs Openapi Typescript Mocks (`web/src/content/docs/docs/openapi/typescript/mocks.mdx`) Copy Section

title: Testing sidebar: label: Overview Copy Chapter

import { Badge } from '@astrojs/starlight/components';
import Examples from '@/components/Examples.astro';

Testing

Testing is an important component of every robust development process. Generate realistic mock data, intercept requests at the network layer, or drive assertions against a running server, all from your specification.

Plugins Copy Chapter

Hey API natively supports the following testing libraries.

• Chance
• Faker
• Falso
• MSW
• Nock
• Playwright
• Supertest

Don't see your library? Let us know by opening an issue.

import { createClient, createConfig } from './client';

export const client = createClient(createConfig());

export * from './sdk.gen';
export * from './types.gen';

import type { Pet } from './client';
// or
import type { Pet } from './client/types.gen';

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    entryFile: false,
    path: 'src/client',
  },
};

import { client } from 'client/client.gen';

client.setConfig({
  baseUrl: 'https://example.com',
});

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-httpx',
      runtimeConfigPath: './src/hey-api.ts',
    },
  ],
};

import type { CreateClientConfig } from './client/client.gen';

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: 'https://example.com',
});

import { createClient } from './client/client';

const myClient = createClient({
  baseUrl: 'https://example.com',
});

const response = await getFoo({
  client: myClient,
});

const response = await getFoo({
  baseUrl: 'https://example.com', // <-- override default configuration
});

</TabItem>
  <TabItem label="eject">
```js title="src/index.ts"
import { client } from 'client/client.gen';

// eject by ID
client.interceptors.request.eject(interceptorId);

// eject by reference
client.interceptors.request.eject(myInterceptor);

</TabItem>
</Tabs>

### Example: Response interceptor

<Tabs>
  <TabItem label="use">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myInterceptor(response) {
  // do something
  return response;
}

interceptorId = client.interceptors.response.use(myInterceptor);

</TabItem>
  <TabItem label="update">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myNewInterceptor(response) {
  // do something
  return response;
}

// update by ID
client.interceptors.response.update(interceptorId, myNewInterceptor);

// update by reference
client.interceptors.response.update(myInterceptor, myNewInterceptor);

import { client } from 'client/client.gen';

client.setConfig({
  auth: () => '<my_token>',
  baseUrl: 'https://example.com',
});

import { client } from 'client/client.gen';

client.interceptors.request.use((request, options) => {
  request.headers.set('Authorization', 'Bearer <my_token>');
  return request;
});

type FooData = {
  path: {
    fooId: number;
  };
  query?: {
    bar?: string;
  };
  url: '/foo/{fooId}';
};

const url = client.buildUrl<FooData>({
  path: {
    fooId: 1,
  },
  query: {
    bar: 'baz',
  },
  url: '/foo/{fooId}',
});
console.log(url); // prints '/foo/1?bar=baz'

import { client } from 'client/client.gen';

client.setConfig({
  fetch: () => {
    /* custom `fetch` method */
  },
});

export { defaultConfig, defineConfig } from './config';
export type { MyPlugin } from './types';

import type { DefinePlugin, Plugin } from '@hey-api/openapi-ts';

export type UserConfig = Plugin.Name<'my-plugin'> &
  Plugin.Hooks &
  Plugin.UserExports & {
    /**
     * User-configurable option for your plugin.
     */
    user?: number | string | {
      age?: number;
      name?: string;
    };
  };

export type Config = Plugin.Name<'my-plugin'> &
  Plugin.Hooks &
  Plugin.Exports & {
    /** Resolved option for your plugin. */
    user: {
      age: number;
      name: string;
    };
  };

export type MyPlugin = DefinePlugin<UserConfig, Config>;

import { definePluginConfig } from '@hey-api/openapi-ts';

import { handler } from './plugin';
import type { MyPlugin } from './types';

export const defaultConfig: MyPlugin['Config'] = {
  config: {
    user: {
      age: 42,
      name: 'Stan Smith',
    },
  },
  handler,
  name: 'my-plugin',
};

/**
 * Type helper for `my-plugin` plugin, returns {@link Plugin.Config} object
 */
export const defineConfig = definePluginConfig(defaultConfig);

</TabItem>
  <TabItem label="input">
```js {8} title="openapi-ts.config.ts"
import { defineConfig } from 'path/to/my-plugin';

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    defineConfig({
      user: 'Joe Doe', // or number to set age
    }),
  ],
};

export const defaultConfig: MyPlugin['Config'] = {
  config: { ... },
  dependencies: ['@hey-api/typescript'],
  handler,
  name: 'my-plugin',
};

import type { PluginContext } from '@hey-api/openapi-ts';
import { coerce } from '@hey-api/openapi-ts';

export const defaultConfig: MyPlugin['Config'] = {
  config: {
    $dependencies: ['validator'],
    validator: coerce((value, context) => {
      if (value === true || value === undefined) {
        return (context as PluginContext).resolveTag('validator');
      }
      return value;
    }),
  },
  dependencies: ['@hey-api/typescript'],
  handler,
  name: 'my-plugin',
};

import { $ } from '@hey-api/openapi-ts';

import type { MyPlugin } from './types';

export const handler: MyPlugin['Handler'] = ({ plugin }) => {
  plugin.forEach('operation', 'schema', (event) => {
    if (event.type === 'operation') {
      // do something with the operation
    } else if (event.type === 'schema') {
      // do something with the schema
    }
  });

  // use the TypeScript DSL to build nodes
  const symbolName = plugin.symbol('user');
  const node = $.const(symbolName)
    .export()
    .assign($.literal(plugin.config.user.name));
  plugin.node(node);
};

</TabItem>
  <TabItem label="types">
```ts {1,5} title="types.ts"
import type { MyPluginImports } from './imports';

/** ... */

export type MyPlugin = DefinePlugin<UserConfig, Config, never, MyPluginImports>;

</TabItem>
  <TabItem label="handler">
```ts {2} title="plugin.ts"
export const handler: MyPlugin['Handler'] = ({ plugin }) => {
  const { myLib } = plugin.imports;
  // use myLib as a typed reference when building nodes
};

import { defineConfig } from 'path/to/my-plugin';

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    defineConfig(),
  ],
};

export const user = 'Stan Smith';

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    'pydantic',
  ],
};

</TabItem>
  <TabItem label="config">
```js {8} title="openapi-python.config.ts"
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'pydantic',
      requests: true,
    },
  ],
};

</TabItem>
  <TabItem label="config">
```js {8} title="openapi-python.config.ts"
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'pydantic',
      definitions: true,
    },
  ],
};

import { client } from 'client/client.gen';

client.setConfig({
  baseURL: 'https://example.com',
});

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-axios',
      runtimeConfigPath: './src/hey-api.ts',
    },
  ],
};

import type { CreateClientConfig } from './client/client.gen';

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseURL: 'https://example.com',
});

import { createClient } from './client/client';

const myClient = createClient({
  baseURL: 'https://example.com',
});

const response = await getFoo({
  client: myClient,
});

const response = await getFoo({
  baseURL: 'https://example.com', // <-- override default configuration
});

import { client } from 'client/client.gen';

client.instance.interceptors.request.use((config) => {
  // do something
  return config;
});

import { client } from 'client/client.gen';

client.setConfig({
  auth: () => '<my_token>',
  baseURL: 'https://example.com',
});

import { client } from 'client/client.gen';

client.instance.interceptors.request.use((config) => {
  config.headers.set('Authorization', 'Bearer <my_token>');
  return config;
});

type FooData = {
  path: {
    fooId: number;
  };
  query?: {
    bar?: string;
  };
  url: '/foo/{fooId}';
};

const url = client.buildUrl<FooData>({
  path: {
    fooId: 1,
  },
  query: {
    bar: 'baz',
  },
  url: '/foo/{fooId}',
});
console.log(url); // prints '/foo/1?bar=baz'

import axios from 'axios';
import { client } from 'client/client.gen';

// Customize the default axios instance
axios.defaults.baseURL = 'https://example.com';

client.setConfig({
  axios: axios,
});

import axios from 'axios';
import { client } from 'client/client.gen';

const customAxiosInstance = axios.create({
  baseURL: 'https://example.com',
});

client.setConfig({
  axios: customAxiosInstance,
});

import { client } from 'client/client.gen';

client.setConfig({
  baseUrl: 'https://example.com',
});

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-fetch',
      runtimeConfigPath: './src/hey-api.ts',
    },
  ],
};

import type { CreateClientConfig } from './client/client.gen';

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: 'https://example.com',
});

import { createClient } from './client/client';

const myClient = createClient({
  baseUrl: 'https://example.com',
});

const response = await getFoo({
  client: myClient,
});

const response = await getFoo({
  baseUrl: 'https://example.com', // <-- override default configuration
});

</TabItem>
  <TabItem label="eject">
```js title="src/index.ts"
import { client } from 'client/client.gen';

// eject by ID
client.interceptors.request.eject(interceptorId);

// eject by reference
client.interceptors.request.eject(myInterceptor);

</TabItem>
</Tabs>

### Example: Response interceptor

<Tabs>
  <TabItem label="use">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myInterceptor(response) {
  // do something
  return response;
}

interceptorId = client.interceptors.response.use(myInterceptor);

</TabItem>
  <TabItem label="update">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myNewInterceptor(response) {
  // do something
  return response;
}

// update by ID
client.interceptors.response.update(interceptorId, myNewInterceptor);

// update by reference
client.interceptors.response.update(myInterceptor, myNewInterceptor);

import { client } from 'client/client.gen';

client.setConfig({
  auth: () => '<my_token>',
  baseUrl: 'https://example.com',
});

import { client } from 'client/client.gen';

client.interceptors.request.use((request, options) => {
  request.headers.set('Authorization', 'Bearer <my_token>');
  return request;
});

type FooData = {
  path: {
    fooId: number;
  };
  query?: {
    bar?: string;
  };
  url: '/foo/{fooId}';
};

const url = client.buildUrl<FooData>({
  path: {
    fooId: 1,
  },
  query: {
    bar: 'baz',
  },
  url: '/foo/{fooId}',
});
console.log(url); // prints '/foo/1?bar=baz'

import { client } from 'client/client.gen';

client.setConfig({
  fetch: () => {
    /* custom `fetch` method */
  },
});

import { client } from 'client/client.gen';

client.setConfig({
  baseUrl: 'https://example.com',
});

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-ky',
      runtimeConfigPath: './src/hey-api.ts',
    },
  ],
};

import type { CreateClientConfig } from './client/client.gen';

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: 'https://example.com',
});

import { createClient } from './client/client';

const myClient = createClient({
  baseUrl: 'https://example.com',
});

const response = await getFoo({
  client: myClient,
});

const response = await getFoo({
  baseUrl: 'https://example.com', // <-- override default configuration
});

</TabItem>
  <TabItem label="eject">
```js title="src/index.ts"
import { client } from 'client/client.gen';

// eject by ID
client.interceptors.request.eject(interceptorId);

// eject by reference
client.interceptors.request.eject(myInterceptor);

</TabItem>
</Tabs>

### Example: Response interceptor

<Tabs>
  <TabItem label="use">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myInterceptor(response) {
  // do something
  return response;
}

interceptorId = client.interceptors.response.use(myInterceptor);

</TabItem>
  <TabItem label="update">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myNewInterceptor(response) {
  // do something
  return response;
}

// update by ID
client.interceptors.response.update(interceptorId, myNewInterceptor);

// update by reference
client.interceptors.response.update(myInterceptor, myNewInterceptor);

import { client } from 'client/client.gen';

client.setConfig({
  auth: () => '<my_token>',
  baseUrl: 'https://example.com',
});

import { client } from 'client/client.gen';

client.interceptors.request.use((request, options) => {
  request.headers.set('Authorization', 'Bearer <my_token>');
  return request;
});

type FooData = {
  path: {
    fooId: number;
  };
  query?: {
    bar?: string;
  };
  url: '/foo/{fooId}';
};

const url = client.buildUrl<FooData>({
  path: {
    fooId: 1,
  },
  query: {
    bar: 'baz',
  },
  url: '/foo/{fooId}',
});
console.log(url); // prints '/foo/1?bar=baz'

import { client } from 'client/client.gen';

client.setConfig({
  ky: ky.create({
    /* custom `ky` instance */
  }),
});

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-next',
      runtimeConfigPath: './src/hey-api.ts',
    },
  ],
};

import type { CreateClientConfig } from './client/client.gen';

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: 'https://example.com',
});

import { client } from 'client/client.gen';

client.setConfig({
  baseUrl: 'https://example.com',
});

import { createClient } from './client/client';

const myClient = createClient({
  baseUrl: 'https://example.com',
});

const response = await getFoo({
  client: myClient,
});

const response = await getFoo({
  baseUrl: 'https://example.com', // <-- override default configuration
});

</TabItem>
  <TabItem label="eject">
```js title="src/index.ts"
import { client } from 'client/client.gen';

// eject by ID
client.interceptors.request.eject(interceptorId);

// eject by reference
client.interceptors.request.eject(myInterceptor);

</TabItem>
</Tabs>

### Example: Response interceptor

<Tabs>
  <TabItem label="use">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myInterceptor(response) {
  // do something
  return response;
}

interceptorId = client.interceptors.response.use(myInterceptor);

</TabItem>
  <TabItem label="update">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myNewInterceptor(response) {
  // do something
  return response;
}

// update by ID
client.interceptors.response.update(interceptorId, myNewInterceptor);

// update by reference
client.interceptors.response.update(myInterceptor, myNewInterceptor);

import { client } from 'client/client.gen';

client.setConfig({
  auth: () => '<my_token>',
  baseUrl: 'https://example.com',
});

import { client } from 'client/client.gen';

client.interceptors.request.use((options) => {
  options.headers.set('Authorization', 'Bearer <my_token>');
});

type FooData = {
  path: {
    fooId: number;
  };
  query?: {
    bar?: string;
  };
  url: '/foo/{fooId}';
};

const url = client.buildUrl<FooData>({
  path: {
    fooId: 1,
  },
  query: {
    bar: 'baz',
  },
  url: '/foo/{fooId}',
});
console.log(url); // prints '/foo/1?bar=baz'

import { client } from 'client/client.gen';

client.setConfig({
  fetch: () => {
    /* custom `fetch` method */
  },
});

import { client } from 'client/client.gen';

client.setConfig({
  baseURL: 'https://example.com',
});

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-nuxt',
      runtimeConfigPath: './src/hey-api.ts',
    },
  ],
};

import type { CreateClientConfig } from './client/client.gen';

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseURL: 'https://example.com',
});

import { createClient } from './client/client';

const myClient = createClient({
  baseURL: 'https://example.com',
});

const response = await getFoo({
  client: myClient,
});

const response = await getFoo({
  baseURL: 'https://example.com', // <-- override default configuration
});

import { client } from 'client/client.gen';

const result = await client.get({
  composable: '$fetch',
  onRequest: (context) => {
    // do something
  },
  url: '/foo',
});

import { client } from 'client/client.gen';

client.setConfig({
  auth: () => '<my_token>',
  baseURL: 'https://example.com',
});

import { client } from 'client/client.gen';

client.setConfig({
  onRequest: ({ options }) => {
    options.headers.set('Authorization', 'Bearer <my_token>');
  },
});

type FooData = {
  path: {
    fooId: number;
  };
  query?: {
    bar?: string;
  };
  url: '/foo/{fooId}';
};

const url = client.buildUrl<FooData>({
  path: {
    fooId: 1,
  },
  query: {
    bar: 'baz',
  },
  url: '/foo/{fooId}',
});
console.log(url); // prints '/foo/1?bar=baz'

import { client } from 'client/client.gen';

client.setConfig({
  $fetch: () => {
    /* custom `$fetch` method */
  },
});

import { client } from 'client/client.gen';

client.setConfig({
  baseUrl: 'https://example.com',
});

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    {
      name: '@hey-api/client-ofetch',
      runtimeConfigPath: './src/hey-api.ts',
    },
  ],
};

import type { CreateClientConfig } from './client/client.gen';

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: 'https://example.com',
});

import { createClient } from './client/client';

const myClient = createClient({
  baseUrl: 'https://example.com',
});

const response = await getFoo({
  client: myClient,
});

const response = await getFoo({
  baseUrl: 'https://example.com', // <-- override default configuration
});

</TabItem>
  <TabItem label="eject">
```js title="src/index.ts"
import { client } from 'client/client.gen';

// eject by ID
client.interceptors.request.eject(interceptorId);

// eject by reference
client.interceptors.request.eject(myInterceptor);

</TabItem>
</Tabs>

### Example: Response interceptor

<Tabs>
  <TabItem label="use">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myInterceptor(response) {
  // do something
  return response;
}

interceptorId = client.interceptors.response.use(myInterceptor);

</TabItem>
  <TabItem label="update">
```js title="src/index.ts"
import { client } from 'client/client.gen';

async function myNewInterceptor(response) {
  // do something
  return response;
}

// update by ID
client.interceptors.response.update(interceptorId, myNewInterceptor);

// update by reference
client.interceptors.response.update(myInterceptor, myNewInterceptor);

import { client } from 'client/client.gen';

client.setConfig({
  onRequest: ({ options }) => {
    // mutate ofetch options (headers, query, etc.)
  },
  onResponse: ({ response }) => {
    // inspect/transform the raw Response
  },
  onRequestError: (ctx) => {
    // handle request errors
  },
  onResponseError: (ctx) => {
    // handle response errors
  },
});

import { client } from 'client/client.gen';

client.setConfig({
  auth: () => '<my_token>',
  baseUrl: 'https://example.com',
});

import { client } from 'client/client.gen';

client.interceptors.request.use((request, options) => {
  request.headers.set('Authorization', 'Bearer <my_token>');
  return request;
});

import { client } from 'client/client.gen';

client.setConfig({
  onRequest: ({ options }) => {
    options.headers.set('Authorization', 'Bearer <my_token>');
  },
});

type FooData = {
  path: {
    fooId: number;
  };
  query?: {
    bar?: string;
  };
  url: '/foo/{fooId}';
};

const url = client.buildUrl<FooData>({
  path: {
    fooId: 1,
  },
  query: {
    bar: 'baz',
  },
  url: '/foo/{fooId}',
});
console.log(url); // prints '/foo/1?bar=baz'

import { ofetch } from 'ofetch';
import { client } from 'client/client.gen';

const customOFetchInstance = ofetch.create({
  onRequest: ({ options }) => {
    // customize request
  },
  onResponse: ({ response }) => {
    // customize response
  },
});

client.setConfig({
  ofetch: customOFetchInstance,
});

export default {
  input: {
    path: 'https://secret.com/protected-spec',
    fetch: {
      headers: {
        Authorization: 'Bearer xxx',
      },
    },
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
};

export default {
  input: {
    path: 'hey-api/backend', // sign up at app.heyapi.dev
    branch: 'main',
  },
};

export default {
  input: 'scalar:@scalar/access-service',
};

</TabItem>
  <TabItem label="config">
```js {4-7} title="openapi-ts.config.ts"
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    header: (ctx) => [
      '/* eslint-disable */',
      ...ctx.defaultValue,
    ],
    path: 'src/client',
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    path: 'src/client',
    source: true,
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    path: 'src/client',
    source: {
      fileName: 'openapi',
      path: './source',
    },
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    path: 'src/client',
    source: {
      callback: (source) => console.log(source),
      path: null,
    },
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    path: 'src/client',
    postProcess: [
      {
        command: 'dprint',
        args: ['fmt', '{{path}}'],
      },
    ],
  },
};

</TabItem>
</Tabs>

## TSConfig Path

We use the [TSConfig file](https://www.typescriptlang.org/tsconfig/) to generate output matching your project's settings. By default, we attempt to find a TSConfig file starting from the location of the `@hey-api/openapi-ts` configuration file and traversing up.

<Tabs>
  <TabItem label="default">
```js {5} title="openapi-ts.config.ts"
export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    path: 'src/client',
    tsConfigPath: undefined,
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: {
    clean: false,
    path: 'src/client',
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    patch: {
      schemas: {
        Foo: (schema) => {
          // convert date-time format to timestamp
          delete schema.properties.updatedAt.format;
          schema.properties.updatedAt.type = 'number';
        },
        Bar: (schema) => {
          // add missing property
          schema.properties.meta = {
            additionalProperties: true,
            type: 'object',
          };
          schema.required = ['meta'];
        },
        Baz: (schema) => {
          // remove property
          delete schema.properties.internalField;
        },
      },
    },
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    validate_EXPERIMENTAL: true,
  },
};

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  parser: {
    filters: {
      deprecated: false,
    },
  },
};