mokkenstorm.dev
fork of hey-api/openapi-ts because I need some additional things
Merge pull request #1496 from hey-api/docs/output-section
docs: split output section into multiple pages
+440
-400
+5
.changeset/orange-squids-press.md
+5
.changeset/orange-squids-press.md
+19
docs/.vitepress/config/en.ts
+19
docs/.vitepress/config/en.ts
···
31
31
{
32
32
items: [
33
33
{
34
+
collapsed: true,
35
+
items: [
36
+
{
37
+
link: '/openapi-ts/output/typescript',
38
+
text: 'TypeScript',
39
+
},
40
+
{
41
+
link: '/openapi-ts/output/sdk',
42
+
text: 'SDK',
43
+
},
44
+
{
45
+
link: '/openapi-ts/output/json-schema',
46
+
text: 'JSON Schema',
47
+
},
48
+
],
34
49
link: '/openapi-ts/output',
35
50
text: 'Output',
36
51
},
···
209
224
{
210
225
link: '/contributing',
211
226
text: 'Contributing',
227
+
},
228
+
{
229
+
link: 'https://github.com/orgs/hey-api/discussions/1495',
230
+
text: 'Roadmap',
212
231
},
213
232
],
214
233
text: '@hey-api',
+1
-1
docs/about.md
+1
-1
docs/about.md
+3
docs/index.md
+3
docs/index.md
···
11
11
- theme: alt
12
12
text: View Demo
13
13
link: https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fsdk.gen.ts,src%2Fclient%2Ftypes.gen.ts
14
+
- theme: alt
15
+
text: Roadmap
16
+
link: https://github.com/orgs/hey-api/discussions/1495
14
17
image:
15
18
src: /logo.png
16
19
alt: logo
+1
-1
docs/openapi-ts/clients.md
+1
-1
docs/openapi-ts/clients.md
+1
-1
docs/openapi-ts/clients/axios.md
+1
-1
docs/openapi-ts/clients/axios.md
+1
-1
docs/openapi-ts/clients/fetch.md
+1
-1
docs/openapi-ts/clients/fetch.md
+1
-1
docs/openapi-ts/clients/legacy.md
+1
-1
docs/openapi-ts/clients/legacy.md
+1
-1
docs/openapi-ts/configuration.md
+1
-1
docs/openapi-ts/configuration.md
···
278
278
You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/types/config.ts) interface.
279
279
280
280
<!--@include: ../examples.md-->
281
-
<!--@include: ../sponsorship.md-->
281
+
<!--@include: ../sponsors.md-->
+1
-1
docs/openapi-ts/custom-plugin.md
+1
-1
docs/openapi-ts/custom-plugin.md
+2
-2
docs/openapi-ts/get-started.md
+2
-2
docs/openapi-ts/get-started.md
···
13
13
This package is in initial development. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
14
14
:::
15
15
16
-
[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) is an OpenAPI to TypeScript codegen trusted more than 700k times each month to generate reliable API clients and SDKs.
16
+
[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) is an OpenAPI to TypeScript codegen trusted more than 700k times each month to generate reliable API clients and SDKs. The code is [MIT-licensed](/license) and free to use. Discover available features below or view our [roadmap](https://github.com/orgs/hey-api/discussions/1495) to learn what's coming next.
17
17
18
18
<button class="buttonLink" @click="(event) => embedProject('hey-api-example')(event)">
19
19
Live demo
···
99
99
It is a good practice to extract your configuration into a separate file. Learn how to do that and discover available options on the [Configuration](/openapi-ts/configuration) page.
100
100
101
101
<!--@include: ../examples.md-->
102
-
<!--@include: ../sponsorship.md-->
102
+
<!--@include: ../sponsors.md-->
+1
-1
docs/openapi-ts/mocks.md
+1
-1
docs/openapi-ts/mocks.md
+2
-363
docs/openapi-ts/output.md
+2
-363
docs/openapi-ts/output.md
···
27
27
└── package.json
28
28
```
29
29
30
-
Each file is an artifact generated by a Hey API plugin. This is the default output, we will cover customizing it on this page. These files also form the base for third-party plugins.
30
+
Each file is an artifact generated by a Hey API plugin. This is the default output, we will cover customizing it in this section. These files also form the base for third-party plugins.
31
31
32
32
Let's go through each file in the `src/client` folder and explain what it looks like, what it does, and how to use it.
33
33
34
-
## TypeScript
35
-
36
-
TypeScript interfaces are located in the `types.gen.ts` file. This is the only file that does not impact your bundle size and runtime performance. It will get discarded during build time, unless you configured to emit runtime [enums](/openapi-ts/output#enums).
37
-
38
-
This file contains three different categories of interfaces created from your input:
39
-
40
-
- reusable components
41
-
- operation request, response, and error data
42
-
- enums
43
-
44
-
Depending on your input and configuration, some of these categories might be missing or differ in your output (and that's okay!).
45
-
46
-
::: code-group
47
-
48
-
```ts [types.gen.ts]
49
-
export type Pet = {
50
-
id?: number;
51
-
name: string;
52
-
};
53
-
54
-
export type AddPetData = {
55
-
body: Pet;
56
-
};
57
-
58
-
export type AddPetResponse = Pet;
59
-
```
60
-
61
-
:::
62
-
63
-
As you can see, everything is exported from `types.gen.ts`. You can import individual exports in your application and use them as necessary.
64
-
65
-
### Configuration
66
-
67
-
You can modify the contents of `types.gen.ts` by configuring the `@hey-api/typescript` plugin. Note that you must specify the default plugins to preserve the default output.
68
-
69
-
```js
70
-
import { defaultPlugins } from '@hey-api/openapi-ts';
71
-
72
-
export default {
73
-
client: '@hey-api/client-fetch',
74
-
input: 'path/to/openapi.json',
75
-
output: 'src/client',
76
-
plugins: [
77
-
...defaultPlugins,
78
-
{
79
-
name: '@hey-api/typescript',
80
-
// ...custom options // [!code ++]
81
-
},
82
-
],
83
-
};
84
-
```
85
-
86
-
## Enums
87
-
88
-
By default, `@hey-api/openapi-ts` will only emit enums as types. You may want to generate runtime artifacts. A good use case is iterating through possible field values without manually typing arrays. To emit runtime enums, set `enums` to a valid option.
89
-
90
-
::: code-group
91
-
92
-
```js [disabled]
93
-
import { defaultPlugins } from '@hey-api/openapi-ts';
94
-
95
-
export default {
96
-
client: '@hey-api/client-fetch',
97
-
input: 'path/to/openapi.json',
98
-
output: 'src/client',
99
-
plugins: [
100
-
...defaultPlugins,
101
-
{
102
-
enums: false, // default // [!code ++]
103
-
name: '@hey-api/typescript',
104
-
},
105
-
],
106
-
};
107
-
```
108
-
109
-
```js [javascript]
110
-
import { defaultPlugins } from '@hey-api/openapi-ts';
111
-
112
-
export default {
113
-
client: '@hey-api/client-fetch',
114
-
input: 'path/to/openapi.json',
115
-
output: 'src/client',
116
-
plugins: [
117
-
...defaultPlugins,
118
-
{
119
-
enums: 'javascript', // [!code ++]
120
-
name: '@hey-api/typescript',
121
-
},
122
-
],
123
-
};
124
-
```
125
-
126
-
```js [typescript]
127
-
import { defaultPlugins } from '@hey-api/openapi-ts';
128
-
129
-
export default {
130
-
client: '@hey-api/client-fetch',
131
-
input: 'path/to/openapi.json',
132
-
output: 'src/client',
133
-
plugins: [
134
-
...defaultPlugins,
135
-
{
136
-
enums: 'typescript', // [!code ++]
137
-
name: '@hey-api/typescript',
138
-
},
139
-
],
140
-
};
141
-
```
142
-
143
-
:::
144
-
145
-
We recommend exporting enums as plain JavaScript objects. [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) are not a type-level extension of JavaScript and pose [typing challenges](https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh).
146
-
147
-
## SDKs
148
-
149
-
SDKs are located in the `sdk.gen.ts` file. SDKs are abstractions on top of clients and serve the same purpose. By default, `@hey-api/openapi-ts` will generate a flat SDK layer. Your choice to use SDKs depends on personal preferences and bundle size considerations.
150
-
151
-
### Flat SDKs
152
-
153
-
This is the default setting. Flat SDKs support tree-shaking and can lead to reduced bundle size over duplicated client calls. The function names are generated from operation IDs or operation location.
154
-
155
-
### Class SDKs
156
-
157
-
Class SDKs do not support tree-shaking which will lead to increased bundle sizes, but some people prefer this option for syntax reasons. The class names are generated from operation tags and method names are generated from operation IDs or operation location.
158
-
159
-
### No SDKs
160
-
161
-
If you prefer to use clients directly or do not need the SDK layer, define `plugins` manually and omit the `@hey-api/sdk` plugin. Type support for clients is currently limited due to popularity of other options. If you'd like to use this option and need better types, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
162
-
163
-
### Configuration
164
-
165
-
You can modify the contents of `sdk.gen.ts` by configuring the `@hey-api/sdk` plugin. Note that you must specify the default plugins to preserve the default output.
166
-
167
-
::: code-group
168
-
169
-
```js [flat]
170
-
import { defaultPlugins } from '@hey-api/openapi-ts';
171
-
172
-
export default {
173
-
client: '@hey-api/client-fetch',
174
-
input: 'path/to/openapi.json',
175
-
output: 'src/client',
176
-
plugins: [
177
-
...defaultPlugins,
178
-
{
179
-
asClass: false, // default // [!code ++]
180
-
name: '@hey-api/sdk',
181
-
},
182
-
],
183
-
};
184
-
```
185
-
186
-
```js [class]
187
-
import { defaultPlugins } from '@hey-api/openapi-ts';
188
-
189
-
export default {
190
-
client: '@hey-api/client-fetch',
191
-
input: 'path/to/openapi.json',
192
-
output: 'src/client',
193
-
plugins: [
194
-
...defaultPlugins,
195
-
{
196
-
asClass: true, // [!code ++]
197
-
name: '@hey-api/sdk',
198
-
},
199
-
],
200
-
};
201
-
```
202
-
203
-
```js [none]
204
-
export default {
205
-
client: '@hey-api/client-fetch',
206
-
input: 'path/to/openapi.json',
207
-
output: 'src/client',
208
-
plugins: [
209
-
'@hey-api/typescript',
210
-
'@hey-api/sdk', // [!code --]
211
-
],
212
-
};
213
-
```
214
-
215
-
:::
216
-
217
-
### Output
218
-
219
-
Below are different outputs depending on your chosen style. No SDKs approach will not generate the `sdk.gen.ts` file.
220
-
221
-
::: code-group
222
-
223
-
```ts [flat]
224
-
import { client, type Options } from '@hey-api/client-fetch';
225
-
226
-
import type { AddPetData, AddPetError, AddPetResponse } from './types.gen';
227
-
228
-
export const addPet = (options: Options<AddPetData>) =>
229
-
(options?.client ?? client).post<AddPetResponse, AddPetError>({
230
-
...options,
231
-
url: '/pet',
232
-
});
233
-
```
234
-
235
-
```ts [class]
236
-
import { client, type Options } from '@hey-api/client-fetch';
237
-
238
-
import type { AddPetData, AddPetError, AddPetResponse } from './types.gen';
239
-
240
-
export class PetService {
241
-
public static addPet(options: Options<AddPetData>) {
242
-
return (options?.client ?? client).post<AddPetResponse, AddPetError>({
243
-
...options,
244
-
url: '/pet',
245
-
});
246
-
}
247
-
}
248
-
```
249
-
250
-
:::
251
-
252
-
### Usage
253
-
254
-
This is how you'd make the same request using each approach.
255
-
256
-
::: code-group
257
-
258
-
```ts [flat]
259
-
import { addPet } from './client/sdk.gen';
260
-
261
-
addPet({
262
-
body: {
263
-
name: 'Kitty',
264
-
},
265
-
});
266
-
```
267
-
268
-
```ts [class]
269
-
import { PetService } from './client/sdk.gen';
270
-
271
-
PetService.addPet({
272
-
body: {
273
-
name: 'Kitty',
274
-
},
275
-
});
276
-
```
277
-
278
-
```ts [none]
279
-
import { client } from '@hey-api/client-fetch';
280
-
281
-
client.post({
282
-
body: {
283
-
name: 'Kitty',
284
-
},
285
-
url: '/pet',
286
-
});
287
-
```
288
-
289
-
:::
290
-
291
-
## JSON Schemas
292
-
293
-
Schemas are located in the `schemas.gen.ts` file. This file contains runtime schemas generated from your OpenAPI specification definitions located in `#/components/schemas`. If you're using OpenAPI 3.1, your schemas are fully JSON Schema compliant and can be used with other tools supporting JSON Schema.
294
-
295
-
### Configuration
296
-
297
-
You can modify the contents of `schemas.gen.ts` by configuring the `@hey-api/schemas` plugin. Note that you must specify the default plugins to preserve the default output.
298
-
299
-
::: code-group
300
-
301
-
```js [json]
302
-
import { defaultPlugins } from '@hey-api/openapi-ts';
303
-
304
-
export default {
305
-
client: '@hey-api/client-fetch',
306
-
input: 'path/to/openapi.json',
307
-
output: 'src/client',
308
-
plugins: [
309
-
...defaultPlugins,
310
-
{
311
-
name: '@hey-api/schemas',
312
-
type: 'json', // [!code ++]
313
-
},
314
-
],
315
-
};
316
-
```
317
-
318
-
```js [form]
319
-
import { defaultPlugins } from '@hey-api/openapi-ts';
320
-
321
-
export default {
322
-
client: '@hey-api/client-fetch',
323
-
input: 'path/to/openapi.json',
324
-
output: 'src/client',
325
-
plugins: [
326
-
...defaultPlugins,
327
-
{
328
-
name: '@hey-api/schemas',
329
-
type: 'form', // [!code ++]
330
-
},
331
-
],
332
-
};
333
-
```
334
-
335
-
```js [disabled]
336
-
import { defaultPlugins } from '@hey-api/openapi-ts';
337
-
338
-
export default {
339
-
client: '@hey-api/client-fetch',
340
-
input: 'path/to/openapi.json',
341
-
output: 'src/client',
342
-
plugins: [
343
-
...defaultPlugins,
344
-
'@hey-api/schemas', // [!code --]
345
-
],
346
-
};
347
-
```
348
-
349
-
:::
350
-
351
-
### Output
352
-
353
-
Below is an example output generated in the `type: 'form'` style. Disabling schemas will not generate the `schemas.gen.ts` file.
354
-
355
-
```ts
356
-
export const PetSchema = {
357
-
required: ['name'],
358
-
properties: {
359
-
id: {
360
-
type: 'integer',
361
-
format: 'int64',
362
-
example: 10,
363
-
},
364
-
name: {
365
-
type: 'string',
366
-
example: 'doggie',
367
-
},
368
-
},
369
-
type: 'object',
370
-
} as const;
371
-
```
372
-
373
-
### Usage
374
-
375
-
A great use case for schemas is client-side form input validation.
376
-
377
-
```ts
378
-
import { $Schema } from './client/schemas.gen';
379
-
380
-
const maxInputLength = $Schema.properties.text.maxLength;
381
-
382
-
if (userInput.length > maxInputLength) {
383
-
throw new Error(`Text length can't exceed ${maxInputLength} characters!`);
384
-
}
385
-
```
386
-
387
34
## Index
388
35
389
36
For convenience, every artifact generated by default plugins is re-exported from `index.ts`. However, we recommend importing artifacts from their files to avoid ambiguity.
···
393
40
import type { Pet } from './client/types.gen'; // [!code ++] // 👍
394
41
```
395
42
396
-
## Client
397
-
398
-
Client package files are located in the `client` folder. This folder will include different files depending on which client you're using. This folder isn't generated by default. If you want to bundle client packages into your output, read the [Bundling](/openapi-ts/clients/fetch#bundling) section.
399
-
400
-
## Plugins
401
-
402
-
The default output generated by Hey API plugins already allows you to build robust clients. However, you might be working with third-party packages and wishing to automate more of your boilerplate. The [Plugins](/openapi-ts/plugins) page covers this topic and more.
403
-
404
43
<!--@include: ../examples.md-->
405
-
<!--@include: ../sponsorship.md-->
44
+
<!--@include: ../sponsors.md-->
+103
docs/openapi-ts/output/json-schema.md
+103
docs/openapi-ts/output/json-schema.md
···
1
+
---
2
+
title: JSON Schema
3
+
description: Learn about files generated with @hey-api/openapi-ts.
4
+
---
5
+
6
+
# JSON Schemas
7
+
8
+
Schemas are located in the `schemas.gen.ts` file. This file contains runtime schemas generated from your OpenAPI specification definitions located in `#/components/schemas`. If you're using OpenAPI 3.1, your schemas are fully JSON Schema compliant and can be used with other tools supporting JSON Schema.
9
+
10
+
## Configuration
11
+
12
+
You can modify the contents of `schemas.gen.ts` by configuring the `@hey-api/schemas` plugin. Note that you must specify the default plugins to preserve the default output.
13
+
14
+
::: code-group
15
+
16
+
```js [json]
17
+
import { defaultPlugins } from '@hey-api/openapi-ts';
18
+
19
+
export default {
20
+
client: '@hey-api/client-fetch',
21
+
input: 'path/to/openapi.json',
22
+
output: 'src/client',
23
+
plugins: [
24
+
...defaultPlugins,
25
+
{
26
+
name: '@hey-api/schemas',
27
+
type: 'json', // [!code ++]
28
+
},
29
+
],
30
+
};
31
+
```
32
+
33
+
```js [form]
34
+
import { defaultPlugins } from '@hey-api/openapi-ts';
35
+
36
+
export default {
37
+
client: '@hey-api/client-fetch',
38
+
input: 'path/to/openapi.json',
39
+
output: 'src/client',
40
+
plugins: [
41
+
...defaultPlugins,
42
+
{
43
+
name: '@hey-api/schemas',
44
+
type: 'form', // [!code ++]
45
+
},
46
+
],
47
+
};
48
+
```
49
+
50
+
```js [disabled]
51
+
import { defaultPlugins } from '@hey-api/openapi-ts';
52
+
53
+
export default {
54
+
client: '@hey-api/client-fetch',
55
+
input: 'path/to/openapi.json',
56
+
output: 'src/client',
57
+
plugins: [
58
+
...defaultPlugins,
59
+
'@hey-api/schemas', // [!code --]
60
+
],
61
+
};
62
+
```
63
+
64
+
:::
65
+
66
+
## Output
67
+
68
+
Below is an example output generated in the `type: 'form'` style. Disabling schemas will not generate the `schemas.gen.ts` file.
69
+
70
+
```ts
71
+
export const PetSchema = {
72
+
required: ['name'],
73
+
properties: {
74
+
id: {
75
+
type: 'integer',
76
+
format: 'int64',
77
+
example: 10,
78
+
},
79
+
name: {
80
+
type: 'string',
81
+
example: 'doggie',
82
+
},
83
+
},
84
+
type: 'object',
85
+
} as const;
86
+
```
87
+
88
+
## Usage
89
+
90
+
A great use case for schemas is client-side form input validation.
91
+
92
+
```ts
93
+
import { $Schema } from './client/schemas.gen';
94
+
95
+
const maxInputLength = $Schema.properties.text.maxLength;
96
+
97
+
if (userInput.length > maxInputLength) {
98
+
throw new Error(`Text length can't exceed ${maxInputLength} characters!`);
99
+
}
100
+
```
101
+
102
+
<!--@include: ../../examples.md-->
103
+
<!--@include: ../../sponsors.md-->
+151
docs/openapi-ts/output/sdk.md
+151
docs/openapi-ts/output/sdk.md
···
1
+
---
2
+
title: SDK
3
+
description: Learn about files generated with @hey-api/openapi-ts.
4
+
---
5
+
6
+
# SDKs
7
+
8
+
SDKs are located in the `sdk.gen.ts` file. SDKs are abstractions on top of clients and serve the same purpose. By default, `@hey-api/openapi-ts` will generate a flat SDK layer. Your choice to use SDKs depends on personal preferences and bundle size considerations.
9
+
10
+
### Flat SDKs
11
+
12
+
This is the default setting. Flat SDKs support tree-shaking and can lead to reduced bundle size over duplicated client calls. The function names are generated from operation IDs or operation location.
13
+
14
+
### Class SDKs
15
+
16
+
Class SDKs do not support tree-shaking which will lead to increased bundle sizes, but some people prefer this option for syntax reasons. The class names are generated from operation tags and method names are generated from operation IDs or operation location.
17
+
18
+
### No SDKs
19
+
20
+
If you prefer to use clients directly or do not need the SDK layer, define `plugins` manually and omit the `@hey-api/sdk` plugin. Type support for clients is currently limited due to popularity of other options. If you'd like to use this option and need better types, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
21
+
22
+
## Configuration
23
+
24
+
You can modify the contents of `sdk.gen.ts` by configuring the `@hey-api/sdk` plugin. Note that you must specify the default plugins to preserve the default output.
25
+
26
+
::: code-group
27
+
28
+
```js [flat]
29
+
import { defaultPlugins } from '@hey-api/openapi-ts';
30
+
31
+
export default {
32
+
client: '@hey-api/client-fetch',
33
+
input: 'path/to/openapi.json',
34
+
output: 'src/client',
35
+
plugins: [
36
+
...defaultPlugins,
37
+
{
38
+
asClass: false, // default // [!code ++]
39
+
name: '@hey-api/sdk',
40
+
},
41
+
],
42
+
};
43
+
```
44
+
45
+
```js [class]
46
+
import { defaultPlugins } from '@hey-api/openapi-ts';
47
+
48
+
export default {
49
+
client: '@hey-api/client-fetch',
50
+
input: 'path/to/openapi.json',
51
+
output: 'src/client',
52
+
plugins: [
53
+
...defaultPlugins,
54
+
{
55
+
asClass: true, // [!code ++]
56
+
name: '@hey-api/sdk',
57
+
},
58
+
],
59
+
};
60
+
```
61
+
62
+
```js [none]
63
+
export default {
64
+
client: '@hey-api/client-fetch',
65
+
input: 'path/to/openapi.json',
66
+
output: 'src/client',
67
+
plugins: [
68
+
'@hey-api/typescript',
69
+
'@hey-api/sdk', // [!code --]
70
+
],
71
+
};
72
+
```
73
+
74
+
:::
75
+
76
+
## Output
77
+
78
+
Below are different outputs depending on your chosen style. No SDKs approach will not generate the `sdk.gen.ts` file.
79
+
80
+
::: code-group
81
+
82
+
```ts [flat]
83
+
import { client, type Options } from '@hey-api/client-fetch';
84
+
85
+
import type { AddPetData, AddPetError, AddPetResponse } from './types.gen';
86
+
87
+
export const addPet = (options: Options<AddPetData>) =>
88
+
(options?.client ?? client).post<AddPetResponse, AddPetError>({
89
+
...options,
90
+
url: '/pet',
91
+
});
92
+
```
93
+
94
+
```ts [class]
95
+
import { client, type Options } from '@hey-api/client-fetch';
96
+
97
+
import type { AddPetData, AddPetError, AddPetResponse } from './types.gen';
98
+
99
+
export class PetService {
100
+
public static addPet(options: Options<AddPetData>) {
101
+
return (options?.client ?? client).post<AddPetResponse, AddPetError>({
102
+
...options,
103
+
url: '/pet',
104
+
});
105
+
}
106
+
}
107
+
```
108
+
109
+
:::
110
+
111
+
## Usage
112
+
113
+
This is how you'd make the same request using each approach.
114
+
115
+
::: code-group
116
+
117
+
```ts [flat]
118
+
import { addPet } from './client/sdk.gen';
119
+
120
+
addPet({
121
+
body: {
122
+
name: 'Kitty',
123
+
},
124
+
});
125
+
```
126
+
127
+
```ts [class]
128
+
import { PetService } from './client/sdk.gen';
129
+
130
+
PetService.addPet({
131
+
body: {
132
+
name: 'Kitty',
133
+
},
134
+
});
135
+
```
136
+
137
+
```ts [none]
138
+
import { client } from '@hey-api/client-fetch';
139
+
140
+
client.post({
141
+
body: {
142
+
name: 'Kitty',
143
+
},
144
+
url: '/pet',
145
+
});
146
+
```
147
+
148
+
:::
149
+
150
+
<!--@include: ../../examples.md-->
151
+
<!--@include: ../../sponsors.md-->
+120
docs/openapi-ts/output/typescript.md
+120
docs/openapi-ts/output/typescript.md
···
1
+
---
2
+
title: TypeScript
3
+
description: Learn about files generated with @hey-api/openapi-ts.
4
+
---
5
+
6
+
# TypeScript
7
+
8
+
TypeScript interfaces are located in the `types.gen.ts` file. This is the only file that does not impact your bundle size and runtime performance. It will get discarded during build time, unless you configured to emit runtime [enums](#enums).
9
+
10
+
This file contains three different categories of interfaces created from your input:
11
+
12
+
- reusable components
13
+
- operation request, response, and error data
14
+
- enums
15
+
16
+
Depending on your input and configuration, some of these categories might be missing or differ in your output (and that's okay!).
17
+
18
+
::: code-group
19
+
20
+
```ts [types.gen.ts]
21
+
export type Pet = {
22
+
id?: number;
23
+
name: string;
24
+
};
25
+
26
+
export type AddPetData = {
27
+
body: Pet;
28
+
};
29
+
30
+
export type AddPetResponse = Pet;
31
+
```
32
+
33
+
:::
34
+
35
+
As you can see, everything is exported from `types.gen.ts`. You can import individual exports in your application and use them as necessary.
36
+
37
+
## Configuration
38
+
39
+
You can modify the contents of `types.gen.ts` by configuring the `@hey-api/typescript` plugin. Note that you must specify the default plugins to preserve the default output.
40
+
41
+
```js
42
+
import { defaultPlugins } from '@hey-api/openapi-ts';
43
+
44
+
export default {
45
+
client: '@hey-api/client-fetch',
46
+
input: 'path/to/openapi.json',
47
+
output: 'src/client',
48
+
plugins: [
49
+
...defaultPlugins,
50
+
{
51
+
name: '@hey-api/typescript',
52
+
// ...custom options // [!code ++]
53
+
},
54
+
],
55
+
};
56
+
```
57
+
58
+
## Enums
59
+
60
+
By default, `@hey-api/openapi-ts` will only emit enums as types. You may want to generate runtime artifacts. A good use case is iterating through possible field values without manually typing arrays. To emit runtime enums, set `enums` to a valid option.
61
+
62
+
::: code-group
63
+
64
+
```js [disabled]
65
+
import { defaultPlugins } from '@hey-api/openapi-ts';
66
+
67
+
export default {
68
+
client: '@hey-api/client-fetch',
69
+
input: 'path/to/openapi.json',
70
+
output: 'src/client',
71
+
plugins: [
72
+
...defaultPlugins,
73
+
{
74
+
enums: false, // default // [!code ++]
75
+
name: '@hey-api/typescript',
76
+
},
77
+
],
78
+
};
79
+
```
80
+
81
+
```js [javascript]
82
+
import { defaultPlugins } from '@hey-api/openapi-ts';
83
+
84
+
export default {
85
+
client: '@hey-api/client-fetch',
86
+
input: 'path/to/openapi.json',
87
+
output: 'src/client',
88
+
plugins: [
89
+
...defaultPlugins,
90
+
{
91
+
enums: 'javascript', // [!code ++]
92
+
name: '@hey-api/typescript',
93
+
},
94
+
],
95
+
};
96
+
```
97
+
98
+
```js [typescript]
99
+
import { defaultPlugins } from '@hey-api/openapi-ts';
100
+
101
+
export default {
102
+
client: '@hey-api/client-fetch',
103
+
input: 'path/to/openapi.json',
104
+
output: 'src/client',
105
+
plugins: [
106
+
...defaultPlugins,
107
+
{
108
+
enums: 'typescript', // [!code ++]
109
+
name: '@hey-api/typescript',
110
+
},
111
+
],
112
+
};
113
+
```
114
+
115
+
:::
116
+
117
+
We recommend exporting enums as plain JavaScript objects. [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) are not a type-level extension of JavaScript and pose [typing challenges](https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh).
118
+
119
+
<!--@include: ../../examples.md-->
120
+
<!--@include: ../../sponsors.md-->
+2
-2
docs/openapi-ts/plugins.md
+2
-2
docs/openapi-ts/plugins.md
···
5
5
6
6
# Plugins
7
7
8
-
Every generated file in your output is created by a plugin. You already learned about the default plugins in [Output](/openapi-ts/output). This page contains all native and selected community plugins.
8
+
Every generated file in your output is created by a plugin. You already learned about the default plugins in [Output](/openapi-ts/output). However, you might be working with third-party packages and wishing to automate more of your boilerplate. This page lists all native and selected community plugins enabling you to do that.
9
9
10
10
## Hey API
11
11
···
58
58
- [add plugin](https://github.com/hey-api/openapi-ts/pulls)
59
59
60
60
<!--@include: ../examples.md-->
61
-
<!--@include: ../sponsorship.md-->
61
+
<!--@include: ../sponsors.md-->
+1
-1
docs/openapi-ts/plugins/ajv.md
+1
-1
docs/openapi-ts/plugins/ajv.md
+1
-1
docs/openapi-ts/plugins/arktype.md
+1
-1
docs/openapi-ts/plugins/arktype.md
+1
-1
docs/openapi-ts/plugins/express.md
+1
-1
docs/openapi-ts/plugins/express.md
+1
-1
docs/openapi-ts/plugins/faker.md
+1
-1
docs/openapi-ts/plugins/faker.md
···
11
11
12
12
[Faker](https://fakerjs.dev/) is a popular library that generates fake (but reasonable) data that can be used for things such as unit testing, performance testing, building demos, and working without a completed backend.
13
13
14
-
<!--@include: ../../sponsorship.md-->
14
+
<!--@include: ../../sponsors.md-->
+1
-1
docs/openapi-ts/plugins/fastify.md
+1
-1
docs/openapi-ts/plugins/fastify.md
+1
-1
docs/openapi-ts/plugins/hono.md
+1
-1
docs/openapi-ts/plugins/hono.md
···
11
11
12
12
[Hono](https://hono.dev/) is a small, simple, and ultrafast web framework built on Web Standards. It works on any JavaScript runtime: Cloudflare Workers, Fastly Compute, Deno, Bun, Vercel, Netlify, AWS Lambda, Lambda@Edge, and Node.js.
13
13
14
-
<!--@include: ../../sponsorship.md-->
14
+
<!--@include: ../../sponsors.md-->
+1
-1
docs/openapi-ts/plugins/joi.md
+1
-1
docs/openapi-ts/plugins/joi.md
+1
-1
docs/openapi-ts/plugins/koa.md
+1
-1
docs/openapi-ts/plugins/koa.md
+1
-1
docs/openapi-ts/plugins/msw.md
+1
-1
docs/openapi-ts/plugins/msw.md
+1
-1
docs/openapi-ts/plugins/nest.md
+1
-1
docs/openapi-ts/plugins/nest.md
+1
-1
docs/openapi-ts/plugins/nock.md
+1
-1
docs/openapi-ts/plugins/nock.md
+1
-1
docs/openapi-ts/plugins/pinia-colada.md
+1
-1
docs/openapi-ts/plugins/pinia-colada.md
+1
-1
docs/openapi-ts/plugins/superstruct.md
+1
-1
docs/openapi-ts/plugins/superstruct.md
+1
-1
docs/openapi-ts/plugins/supertest.md
+1
-1
docs/openapi-ts/plugins/supertest.md
+1
-1
docs/openapi-ts/plugins/swr.md
+1
-1
docs/openapi-ts/plugins/swr.md
+1
-1
docs/openapi-ts/plugins/tanstack-query.md
+1
-1
docs/openapi-ts/plugins/tanstack-query.md
+1
-1
docs/openapi-ts/plugins/typebox.md
+1
-1
docs/openapi-ts/plugins/typebox.md
+1
-1
docs/openapi-ts/plugins/valibot.md
+1
-1
docs/openapi-ts/plugins/valibot.md
+1
-1
docs/openapi-ts/plugins/yup.md
+1
-1
docs/openapi-ts/plugins/yup.md
+1
-1
docs/openapi-ts/plugins/zod.md
+1
-1
docs/openapi-ts/plugins/zod.md
+1
-1
docs/openapi-ts/plugins/zustand.md
+1
-1
docs/openapi-ts/plugins/zustand.md
+1
-1
docs/openapi-ts/state-management.md
+1
-1
docs/openapi-ts/state-management.md
+1
-1
docs/openapi-ts/transformers.md
+1
-1
docs/openapi-ts/transformers.md
+1
-1
docs/openapi-ts/validators.md
+1
-1
docs/openapi-ts/validators.md
+1
-1
docs/openapi-ts/web-frameworks.md
+1
-1
docs/openapi-ts/web-frameworks.md
docs/sponsorship.md
docs/sponsors.md
docs/sponsorship.md
docs/sponsors.md