···1313- works with CLI, Node.js, or npx
1414- supports OpenAPI 2.0, 3.0, and 3.1 specifications
1515- supports both JSON and YAML input files
1616-- supports external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
1716- generates TypeScript interfaces, REST clients, and JSON Schemas
1817- Fetch API, Axios, Angular, Node.js, and XHR clients available
1919-- abortable requests through cancellable promise pattern
20182119## Documentation
2220
+12
docs/CHANGELOG.md
···11# @hey-api/docs
2233+## 0.5.5
44+55+### Patch Changes
66+77+- docs: add migration for v0.45.0 ([#569](https://github.com/hey-api/openapi-ts/pull/569))
88+99+## 0.5.4
1010+1111+### Patch Changes
1212+1313+- docs: add format and lint migration for 0.44.0 ([#546](https://github.com/hey-api/openapi-ts/pull/546))
1414+315## 0.5.3
416517### Patch Changes
+1-1
docs/openapi-ts/clients.md
···11111212## Legacy Clients
13131414-Before standalone client packages, clients were generated using `openapi-ts`. If you want to use a client that isn't published as a standalone package, you can explicitly set the `client` config option to generate it.
1414+Before standalone client packages, clients were generated using `openapi-ts`. If you want to generate a legacy client that isn't published as a standalone package, you can use the `client` config option.
15151616::: code-group
1717
+58-21
docs/openapi-ts/configuration.md
···40404141## Clients
42424343-By default, `openapi-ts` will try to guess your client based on your project dependencies. If we don't get it right, you can specify the desired client
4343+By default, `openapi-ts` will generate a Fetch API client. If you want a different client, you can specify it using the `client` option.
44444545::: code-group
4646···101101You might not need a `node` client. Fetch API is [experimental](https://nodejs.org/docs/latest-v18.x/api/globals.html#fetch) in Node.js v18 and [stable](https://nodejs.org/docs/latest-v21.x/api/globals.html#fetch) in Node.js v21. We recommend upgrading to the latest Node.js version.
102102:::
103103104104+<!--
105105+TODO: uncomment after c12 supports multiple configs
106106+see https://github.com/unjs/c12/issues/92
107107+-->
108108+<!-- ### Multiple Clients
109109+110110+If you want to generate multiple clients with a single `openapi-ts` command, you can provide an array of configuration objects.
111111+112112+```js
113113+import { defineConfig } from '@hey-api/openapi-ts';
114114+115115+export default defineConfig([
116116+ {
117117+ client: 'fetch',
118118+ input: 'path/to/openapi_one.json',
119119+ output: 'src/client_one',
120120+ },
121121+ {
122122+ client: 'axios',
123123+ input: 'path/to/openapi_two.json',
124124+ output: 'src/client_two',
125125+ },
126126+])
127127+``` -->
128128+104129## Formatting
105130106106-By default, `openapi-ts` will not automatically format your client. To enable this feature, set `format` to a valid formatter.
131131+By default, `openapi-ts` will not automatically format your client. To enable this feature, set `output.format` to a valid formatter.
107132108133::: code-group
109134110110-```js{2} [disabled]
135135+```js{4} [disabled]
111136export default {
112112- format: false,
113137 input: 'path/to/openapi.json',
114114- output: 'src/client',
138138+ output: {
139139+ format: false,
140140+ path: 'src/client',
141141+ },
115142}
116143```
117144118118-```js{2} [prettier]
145145+```js{4} [prettier]
119146export default {
120120- format: 'prettier',
121147 input: 'path/to/openapi.json',
122122- output: 'src/client',
148148+ output: {
149149+ format: 'prettier',
150150+ path: 'src/client',
151151+ },
123152}
124153```
125154126126-```js{2} [biome]
155155+```js{4} [biome]
127156export default {
128128- format: 'biome',
129157 input: 'path/to/openapi.json',
130130- output: 'src/client',
158158+ output: {
159159+ format: 'biome',
160160+ path: 'src/client',
161161+ },
131162}
132163```
133164···137168138169## Linting
139170140140-For performance reasons, `openapi-ts` does not automatically lint your client. To enable this feature, set `lint` to a valid linter.
171171+For performance reasons, `openapi-ts` does not automatically lint your client. To enable this feature, set `output.lint` to a valid linter.
141172142173::: code-group
143174144144-```js{3} [disabled]
175175+```js{4} [disabled]
145176export default {
146177 input: 'path/to/openapi.json',
147147- lint: false,
148148- output: 'src/client',
178178+ output: {
179179+ lint: false,
180180+ path: 'src/client',
181181+ },
149182}
150183```
151184152152-```js{3} [eslint]
185185+```js{4} [eslint]
153186export default {
154187 input: 'path/to/openapi.json',
155155- lint: 'eslint',
156156- output: 'src/client',
188188+ output: {
189189+ lint: 'eslint',
190190+ path: 'src/client',
191191+ },
157192}
158193```
159194160160-```js{3} [biome]
195195+```js{4} [biome]
161196export default {
162197 input: 'path/to/openapi.json',
163163- lint: 'biome',
164164- output: 'src/client',
198198+ output: {
199199+ lint: 'biome',
200200+ path: 'src/client',
201201+ },
165202}
166203```
167204
-2
docs/openapi-ts/get-started.md
···2020- works with CLI, Node.js, or npx
2121- supports OpenAPI 2.0, 3.0, and 3.1 specifications
2222- supports both JSON and YAML input files
2323-- supports external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
2423- generates TypeScript interfaces, REST clients, and JSON Schemas
2524- Fetch API, Axios, Angular, Node.js, and XHR clients available
2626-- abortable requests through cancellable promise pattern
27252826## Quick Start
2927
+45-1
docs/openapi-ts/migrating.md
···50505151This config option is deprecated and will be removed in favor of [clients](./clients).
52525353+## v0.45.0
5454+5555+### Removed `client` inference
5656+5757+`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.
5858+5959+```js{2}
6060+export default {
6161+ client: 'axios',
6262+ input: 'path/to/openapi.json',
6363+ output: 'src/client',
6464+}
6565+```
6666+6767+## v0.44.0
6868+6969+### Moved `format`
7070+7171+This config option has been moved. You can now configure formatter using the `output.format` option.
7272+7373+```js{4}
7474+export default {
7575+ input: 'path/to/openapi.json',
7676+ output: {
7777+ format: 'prettier',
7878+ path: 'src/client',
7979+ },
8080+}
8181+```
8282+8383+### Moved `lint`
8484+8585+This config option has been moved. You can now configure linter using the `output.lint` option.
8686+8787+```js{4}
8888+export default {
8989+ input: 'path/to/openapi.json',
9090+ output: {
9191+ lint: 'eslint',
9292+ path: 'src/client',
9393+ },
9494+}
9595+```
9696+5397## v0.43.0
54985599### Removed `enums.gen.ts`
···360404361405## OpenAPI TypeScript Codegen
362406363363-`openapi-ts` was originally forked from Ferdi Koomen's [openapi-typescript-codegen](https://github.com/ferdikoomen/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 here and scroll up to the release you're migrating to.
407407+`openapi-ts` was originally forked from Ferdi Koomen's [openapi-typescript-codegen](https://github.com/ferdikoomen/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](#v0-27-24) and scroll to the release you're migrating to.
···1212 if (item.$ref) {
1313 // Fetch the paths to the definitions, this converts:
1414 // "#/components/schemas/Form" to ["components", "schemas", "Form"]
1515- const paths = item.$ref
1616- .replace(/^#/g, '')
1717- .split('/')
1818- .filter((item) => item);
1515+ const paths = item.$ref.replace(/^#/g, '').split('/').filter(Boolean);
19162017 // Try to find the reference by walking down the path,
2118 // if we cannot find it, then we throw an error.
···11-import type { Model } from '../../common/interfaces/client';
11+import type { Client } from '../../../types/client';
22import { reservedWords } from '../../common/parser/reservedWords';
33import { getType } from '../../common/parser/type';
44import type { OpenApi } from '../interfaces/OpenApi';
55import { getModel } from './getModel';
6677-export const getModels = (openApi: OpenApi): Model[] => {
77+export const getModels = (
88+ openApi: OpenApi,
99+): Pick<Client, 'models' | 'types'> => {
1010+ const types: Client['types'] = {};
1111+ let models: Client['models'] = [];
1212+813 if (!openApi.components) {
99- return [];
1414+ return {
1515+ models,
1616+ types,
1717+ };
1018 }
11191212- let models: Model[] = [];
1313-1420 Object.entries(openApi.components.schemas ?? {}).forEach(
1521 ([definitionName, definition]) => {
1622 const definitionType = getType({ type: definitionName });
2323+ const name = definitionType.base.replace(reservedWords, '_$1');
2424+ const meta = {
2525+ $ref: `#/components/schemas/${definitionName}`,
2626+ name,
2727+ };
2828+ types[name] = meta;
1729 const model = getModel({
1830 definition,
1931 isDefinition: true,
2020- meta: {
2121- $ref: `#/components/schemas/${definitionName}`,
2222- name: definitionType.base.replace(reservedWords, '_$1'),
2323- },
3232+ meta,
2433 openApi,
3434+ types,
2535 });
2636 models = [...models, model];
2737 },
···3545 }
36463747 const definitionType = getType({ type: definitionName });
4848+ /**
4949+ * Prefix parameter names to avoid name conflicts with schemas.
5050+ * Assuming people are mostly interested in importing schema types
5151+ * and don't care about this name as much. It should be resolved in
5252+ * a cleaner way, there just isn't a good deduplication strategy
5353+ * today. This is a workaround in the meantime, hopefully reducing
5454+ * the chance of conflicts.
5555+ *
5656+ * Example where this would break: schema named `ParameterFoo` and
5757+ * parameter named `Foo` (this would transform to `ParameterFoo`)
5858+ *
5959+ * Note: there's a related code to this workaround in `getType()`
6060+ * method that needs to be cleaned up when this is addressed.
6161+ */
6262+ const name = `Parameter${definitionType.base.replace(reservedWords, '_$1')}`;
6363+ const meta = {
6464+ $ref: `#/components/parameters/${definitionName}`,
6565+ name,
6666+ };
6767+ types[name] = meta;
3868 const model = getModel({
3969 definition: schema,
4070 isDefinition: true,
4141- meta: {
4242- $ref: `#/components/parameters/${definitionName}`,
4343- /**
4444- * Prefix parameter names to avoid name conflicts with schemas.
4545- * Assuming people are mostly interested in importing schema types
4646- * and don't care about this name as much. It should be resolved in
4747- * a cleaner way, there just isn't a good deduplication strategy
4848- * today. This is a workaround in the meantime, hopefully reducing
4949- * the chance of conflicts.
5050- *
5151- * Example where this would break: schema named `ParameterFoo` and
5252- * parameter named `Foo` (this would transform to `ParameterFoo`)
5353- *
5454- * Note: there's a related code to this workaround in `getType()`
5555- * method that needs to be cleaned up when this is addressed.
5656- */
5757- name: `Parameter${definitionType.base.replace(reservedWords, '_$1')}`,
5858- },
7171+ meta,
5972 openApi,
7373+ types,
6074 });
6175 model.deprecated = definition.deprecated;
6276 model.description = definition.description || null;
···6478 },
6579 );
66806767- return models;
8181+ return {
8282+ models,
8383+ types,
8484+ };
6885};
···280280};
281281282282/**
283283+ * This is a simple enum with strings
284284+ */
285285+export type foo_bar_enum = 'Success' | 'Warning' | 'Error' | 'ØÆÅ字符串';
286286+287287+/**
283288 * This is a model with one enum
284289 */
285290export type ModelWithEnum = {
···298303};
299304300305/**
306306+ * These are the HTTP error code enums
307307+ */
308308+export type statusCode = '100' | '200 FOO' | '300 FOO_BAR' | '400 foo-bar' | '500 foo.bar' | '600 foo&bar';
309309+310310+/**
301311 * This is a model with one enum with escaped name
302312 */
303313export type ModelWithEnumWithHyphen = {
304314 'foo-bar-baz-qux'?: '3.0';
305315};
316316+317317+export type foo_bar_baz_qux = '3.0';
306318307319/**
308320 * This is a model with one enum
···716728 foo: 'Corge';
717729};
718730731731+export type foo = 'Bar';
732732+719733export type ModelWithNestedArrayEnumsDataFoo = 'foo' | 'bar';
720734721735export type ModelWithNestedArrayEnumsDataBar = 'baz' | 'qux';
···773787 */
774788 value?: -10 | -1 | 0 | 1 | 3 | 6 | 12;
775789};
790790+791791+/**
792792+ * Период
793793+ */
794794+export type value = -10 | -1 | 0 | 1 | 3 | 6 | 12;
776795777796/**
778797 * Some description with `back ticks`
···280280};
281281282282/**
283283+ * This is a simple enum with strings
284284+ */
285285+export type foo_bar_enum = 'Success' | 'Warning' | 'Error' | 'ØÆÅ字符串';
286286+287287+/**
283288 * This is a model with one enum
284289 */
285290export type ModelWithEnum = {
···298303};
299304300305/**
306306+ * These are the HTTP error code enums
307307+ */
308308+export type statusCode = '100' | '200 FOO' | '300 FOO_BAR' | '400 foo-bar' | '500 foo.bar' | '600 foo&bar';
309309+310310+/**
301311 * This is a model with one enum with escaped name
302312 */
303313export type ModelWithEnumWithHyphen = {
304314 'foo-bar-baz-qux'?: '3.0';
305315};
316316+317317+export type foo_bar_baz_qux = '3.0';
306318307319/**
308320 * This is a model with one enum
···716728 foo: 'Corge';
717729};
718730731731+export type foo = 'Bar';
732732+719733export type ModelWithNestedArrayEnumsDataFoo = 'foo' | 'bar';
720734721735export type ModelWithNestedArrayEnumsDataBar = 'baz' | 'qux';
···773787 */
774788 value?: -10 | -1 | 0 | 1 | 3 | 6 | 12;
775789};
790790+791791+/**
792792+ * Период
793793+ */
794794+export type value = -10 | -1 | 0 | 1 | 3 | 6 | 12;
776795777796/**
778797 * Some description with `back ticks`
···2424 /**
2525 * This is a simple boolean with default value
2626 */
2727- parameterBoolean: boolean | null;
2727+ parameterBoolean?: boolean | null;
2828 /**
2929 * This is a simple enum with default value
3030 */
3131- parameterEnum: 'Success' | 'Warning' | 'Error';
3131+ parameterEnum?: 'Success' | 'Warning' | 'Error';
3232 /**
3333 * This is a simple model with default value
3434 */
3535- parameterModel: ModelWithString | null;
3535+ parameterModel?: ModelWithString | null;
3636 /**
3737 * This is a simple number with default value
3838 */
3939- parameterNumber: number | null;
3939+ parameterNumber?: number | null;
4040 /**
4141 * This is a simple string with default value
4242 */
4343- parameterString: string | null;
4343+ parameterString?: string | null;
4444};
45454646export type CallWithDefaultOptionalParametersData = {
4747 /**
4848 * This is a simple boolean that is optional with default value
4949 */
5050- parameterBoolean: boolean;
5050+ parameterBoolean?: boolean;
5151 /**
5252 * This is a simple enum that is optional with default value
5353 */
5454- parameterEnum: 'Success' | 'Warning' | 'Error';
5454+ parameterEnum?: 'Success' | 'Warning' | 'Error';
5555 /**
5656 * This is a simple model that is optional with default value
5757 */
5858- parameterModel: ModelWithString;
5858+ parameterModel?: ModelWithString;
5959 /**
6060 * This is a simple number that is optional with default value
6161 */
6262- parameterNumber: number;
6262+ parameterNumber?: number;
6363 /**
6464 * This is a simple string that is optional with default value
6565 */
6666- parameterString: string;
6666+ parameterString?: string;
6767};
68686969export type CallToTestOrderOfParamsData = {
7070 /**
7171 * This is a optional string with default
7272 */
7373- parameterOptionalStringWithDefault: string;
7373+ parameterOptionalStringWithDefault?: string;
7474 /**
7575 * This is a optional string with empty default
7676 */
7777- parameterOptionalStringWithEmptyDefault: string;
7777+ parameterOptionalStringWithEmptyDefault?: string;
7878 /**
7979 * This is a optional string with no default
8080 */
···8282 /**
8383 * This is a string that can be null with default
8484 */
8585- parameterStringNullableWithDefault: string | null;
8585+ parameterStringNullableWithDefault?: string | null;
8686 /**
8787 * This is a string that can be null with no default
8888 */
···113113 req: CallToTestOrderOfParamsData;
114114 };
115115 };
116116-};116116+};
···280280};
281281282282/**
283283+ * This is a simple enum with strings
284284+ */
285285+export type foo_bar_enum = 'Success' | 'Warning' | 'Error' | 'ØÆÅ字符串';
286286+287287+/**
283288 * This is a model with one enum
284289 */
285290export type ModelWithEnum = {
···298303};
299304300305/**
306306+ * These are the HTTP error code enums
307307+ */
308308+export type statusCode = '100' | '200 FOO' | '300 FOO_BAR' | '400 foo-bar' | '500 foo.bar' | '600 foo&bar';
309309+310310+/**
301311 * This is a model with one enum with escaped name
302312 */
303313export type ModelWithEnumWithHyphen = {
304314 'foo-bar-baz-qux'?: '3.0';
305315};
316316+317317+export type foo_bar_baz_qux = '3.0';
306318307319/**
308320 * This is a model with one enum
···716728 foo: 'Corge';
717729};
718730731731+export type foo = 'Bar';
732732+719733export type ModelWithNestedArrayEnumsDataFoo = 'foo' | 'bar';
720734721735export type ModelWithNestedArrayEnumsDataBar = 'baz' | 'qux';
···773787 */
774788 value?: -10 | -1 | 0 | 1 | 3 | 6 | 12;
775789};
790790+791791+/**
792792+ * Период
793793+ */
794794+export type value = -10 | -1 | 0 | 1 | 3 | 6 | 12;
776795777796/**
778797 * Some description with `back ticks`