fork of hey-api/openapi-ts because I need some additional things
Merge pull request #2621 from hey-api/docs/nav-core
docs: simplify navigation
+141
-133
+7
-1
.changeset/brown-paws-design.md
+7
-1
.changeset/brown-paws-design.md
···
2
2
'@hey-api/openapi-ts': minor
3
3
---
4
4
5
-
feat: add symbol api
5
+
feat: Symbol API
6
+
7
+
### Symbol API
8
+
9
+
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.
10
+
11
+
We will update the [custom plugin guide](https://heyapi.dev/openapi-ts/plugins/custom) once the Plugin API becomes more stable.
+1
-1
.changeset/cuddly-bears-deny.md
+1
-1
.changeset/cuddly-bears-deny.md
+5
-1
.changeset/thirty-shoes-end.md
+5
-1
.changeset/thirty-shoes-end.md
···
2
2
'@hey-api/openapi-ts': minor
3
3
---
4
4
5
-
feat(pinia-colada): remove groupByTag option
5
+
feat(pinia-colada): remove `groupByTag` option
6
+
7
+
### Removed `groupByTag` Pinia Colada option
8
+
9
+
This option has been removed to provide a more consistent API across plugins. We plan to bring it back in a future release.
+26
-27
docs/.vitepress/config/en.ts
+26
-27
docs/.vitepress/config/en.ts
···
48
48
link: '/openapi-ts/configuration',
49
49
text: 'Configuration',
50
50
},
51
+
{
52
+
link: '/openapi-ts/output',
53
+
text: 'Output',
54
+
},
51
55
],
52
56
text: 'Introduction',
53
57
},
···
57
61
collapsed: true,
58
62
items: [
59
63
{
60
-
link: '/openapi-ts/output/typescript',
64
+
link: '/openapi-ts/plugins/typescript',
61
65
text: 'TypeScript',
62
66
},
63
67
{
64
-
link: '/openapi-ts/output/sdk',
68
+
link: '/openapi-ts/plugins/sdk',
65
69
text: 'SDK',
66
70
},
67
71
{
68
-
link: '/openapi-ts/output/client',
69
-
text: 'Client',
72
+
link: '/openapi-ts/plugins/transformers',
73
+
text: 'Transformers',
70
74
},
71
75
{
72
-
link: '/openapi-ts/output/json-schema',
73
-
text: 'JSON Schema',
76
+
link: '/openapi-ts/plugins/schemas',
77
+
text: 'Schemas',
74
78
},
75
79
],
76
-
link: '/openapi-ts/output',
77
-
text: 'Output',
78
-
},
79
-
{
80
-
collapsed: true,
81
-
items: [
82
-
{
83
-
link: '/openapi-ts/plugins/custom',
84
-
text: 'Custom Plugin',
85
-
},
86
-
],
87
-
link: '/openapi-ts/plugins',
88
-
text: 'Plugins',
80
+
link: '/openapi-ts/core',
81
+
text: 'Core',
89
82
},
90
83
{
91
84
collapsed: true,
···
113
106
{
114
107
link: '/openapi-ts/clients/effect',
115
108
text: 'Effect <span data-soon>soon</span>',
116
-
},
117
-
{
118
-
link: '/openapi-ts/clients/custom',
119
-
text: 'Custom Client',
120
109
},
121
110
{
122
111
link: '/openapi-ts/clients/legacy',
···
164
153
],
165
154
link: '/openapi-ts/validators',
166
155
text: 'Validators',
167
-
},
168
-
{
169
-
link: '/openapi-ts/transformers',
170
-
text: 'Transformers',
171
156
},
172
157
{
173
158
collapsed: true,
···
257
242
],
258
243
link: '/openapi-ts/web-frameworks',
259
244
text: 'Web Frameworks',
245
+
},
246
+
{
247
+
collapsed: true,
248
+
items: [
249
+
{
250
+
link: '/openapi-ts/plugins/custom',
251
+
text: 'Plugin',
252
+
},
253
+
{
254
+
link: '/openapi-ts/clients/custom',
255
+
text: 'Client',
256
+
},
257
+
],
258
+
text: 'Custom',
260
259
},
261
260
],
262
261
text: 'Guides and Concepts',
+1
-1
docs/index.md
+1
-1
docs/index.md
···
3
3
4
4
hero:
5
5
name: One OpenAPI spec.<br/>Infinite outputs.
6
-
tagline: Codegen for JavaScript/TypeScript projects. Trusted over 2,000,000 times each month to generate reliable API clients and SDKs.
6
+
tagline: Codegen for JavaScript/TypeScript projects. Trusted over 2,500,000 times each month to generate reliable API clients and SDKs.
7
7
actions:
8
8
- link: /openapi-ts/get-started
9
9
text: Get Started
+22
docs/openapi-ts/core.md
+22
docs/openapi-ts/core.md
···
1
+
---
2
+
title: Core Plugins
3
+
description: Learn about the core plugins provided by Hey API.
4
+
---
5
+
6
+
# Core
7
+
8
+
Apart from being responsible for the default output, core plugins are the foundation for other plugins. Instead of creating their own primitives, other plugins can reuse the artifacts from core plugins. This results in a smaller output size and a better user experience.
9
+
10
+
## Options
11
+
12
+
Hey API provides the following core plugins.
13
+
14
+
- [TypeScript](/openapi-ts/plugins/typescript)
15
+
- [SDK](/openapi-ts/plugins/sdk)
16
+
- [Transformers](/openapi-ts/plugins/transformers)
17
+
- [Schemas](/openapi-ts/plugins/schemas)
18
+
19
+
Need another core plugin? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues).
20
+
21
+
<!--@include: ../partials/examples.md-->
22
+
<!--@include: ../partials/sponsors.md-->
+1
-1
docs/openapi-ts/get-started.md
+1
-1
docs/openapi-ts/get-started.md
···
9
9
10
10
# Get Started
11
11
12
-
[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) is an OpenAPI to TypeScript codegen trusted over 2,000,000 times each month to generate reliable API clients and SDKs. The code is [MIT-licensed](/openapi-ts/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.
12
+
[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) is an OpenAPI to TypeScript codegen trusted over 2,500,000 times each month to generate reliable API clients and SDKs. The code is [MIT-licensed](/openapi-ts/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.
13
13
14
14
### Demo
15
15
+13
-1
docs/openapi-ts/migrating.md
+13
-1
docs/openapi-ts/migrating.md
···
7
7
8
8
While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code. If you run into a problem with migration, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
9
9
10
+
## v0.83.0
11
+
12
+
### Symbol API
13
+
14
+
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.
15
+
16
+
We will update the [custom plugin guide](/openapi-ts/plugins/custom) once the Plugin API becomes more stable.
17
+
18
+
### Removed `groupByTag` Pinia Colada option
19
+
20
+
This option has been removed to provide a more consistent API across plugins. We plan to bring it back in a future release.
21
+
10
22
## v0.82.0
11
23
12
-
### Added Hooks API
24
+
### Hooks API
13
25
14
26
This release adds the [Hooks API](/openapi-ts/configuration/parser#hooks), 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.
15
27
+32
-8
docs/openapi-ts/output.md
+32
-8
docs/openapi-ts/output.md
···
5
5
6
6
# Output
7
7
8
-
Learn about files generated with `@hey-api/openapi-ts`.
9
-
10
-
::: tip
11
-
Your actual output depends on your Hey API configuration. It may contain a different number of files and their contents might differ.
12
-
:::
8
+
Every generated file in your output folder is created by a plugin. This page describes the default output, but similar logic applies to all plugins.
13
9
14
10
## Overview
15
11
···
30
26
└── package.json
31
27
```
32
28
33
-
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.
29
+
Your actual output depends on your Hey API configuration. It may contain a different number of files and their contents might differ.
34
30
35
31
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.
36
32
37
-
## Index
33
+
## Client
34
+
35
+
`client.gen.ts` is generated by [client plugins](/openapi-ts/clients). If you choose to generate SDKs (enabled by default), we use the Fetch client unless specified otherwise.
38
36
39
-
`index.ts` is the only file not generated by a specific plugin. It's meant for convenience and by default, it re-exports every artifact generated by default plugins (TypeScript and SDK).
37
+
::: code-group
38
+
39
+
```ts [client.gen.ts]
40
+
import { createClient, createConfig } from './client';
41
+
42
+
export const client = createClient(createConfig());
43
+
```
44
+
45
+
:::
46
+
47
+
The contents of this file are consumed by SDKs, but you can also import `client` in your application to perform additional configuration or send manual requests.
48
+
49
+
### Bundle
50
+
51
+
Client plugins provide their bundles inside `client` and `core` folders. The contents of these folders don't depend on the provided input. Everything inside these folders serves as a scaffolding so the generated code can make HTTP requests.
52
+
53
+
## TypeScript
54
+
55
+
You can learn more on the [TypeScript](/openapi-ts/plugins/typescript) page.
56
+
57
+
## SDK
58
+
59
+
You can learn more on the [SDK](/openapi-ts/plugins/sdk) page.
60
+
61
+
## Barrel File
62
+
63
+
`index.ts` is not generated by any specific plugin. It's meant for convenience and by default, it re-exports every artifact generated by default plugins (TypeScript and SDK).
40
64
41
65
::: code-group
42
66
-27
docs/openapi-ts/output/client.md
-27
docs/openapi-ts/output/client.md
···
1
-
---
2
-
title: Client
3
-
description: Learn about files generated with @hey-api/openapi-ts.
4
-
---
5
-
6
-
# Client
7
-
8
-
`client.gen.ts` is generated by [client plugins](/openapi-ts/clients). If you choose to generate SDKs (enabled by default), we use the Fetch client unless specified otherwise.
9
-
10
-
::: code-group
11
-
12
-
```ts [client.gen.ts]
13
-
import { createClient, createConfig } from './client';
14
-
15
-
export const client = createClient(createConfig());
16
-
```
17
-
18
-
:::
19
-
20
-
The contents of this file are consumed by SDKs, but you can also import `client` in your application to perform additional configuration or send manual requests.
21
-
22
-
## Bundle
23
-
24
-
Client plugins provide their bundles inside `client` and `core` folders. The contents of these folders don't depend on the provided input. Everything inside these folders serves as a scaffolding so the generated code can make HTTP requests.
25
-
26
-
<!--@include: ../../partials/examples.md-->
27
-
<!--@include: ../../partials/sponsors.md-->
docs/openapi-ts/output/json-schema.md
docs/openapi-ts/plugins/schemas.md
docs/openapi-ts/output/json-schema.md
docs/openapi-ts/plugins/schemas.md
docs/openapi-ts/output/sdk.md
docs/openapi-ts/plugins/sdk.md
docs/openapi-ts/output/sdk.md
docs/openapi-ts/plugins/sdk.md
docs/openapi-ts/output/typescript.md
docs/openapi-ts/plugins/typescript.md
docs/openapi-ts/output/typescript.md
docs/openapi-ts/plugins/typescript.md
-61
docs/openapi-ts/plugins.md
-61
docs/openapi-ts/plugins.md
···
1
-
---
2
-
title: Plugins
3
-
description: Learn about and discover available plugins.
4
-
---
5
-
6
-
# Plugins
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). 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
-
10
-
## Core
11
-
12
-
Apart from being responsible for the default output, core plugins are the foundation for other plugins. Instead of creating their own primitives, other plugins can reuse the artifacts from core plugins. This results in a smaller output size and a better user experience.
13
-
14
-
- [`@hey-api/schemas`](/openapi-ts/output/json-schema) - export OpenAPI definitions as JavaScript objects
15
-
- [`@hey-api/sdk`](/openapi-ts/output/sdk) - robust and polished SDKs
16
-
- [`@hey-api/transformers`](/openapi-ts/transformers) - response data transformer functions
17
-
- [`@hey-api/typescript`](/openapi-ts/output/typescript) - TypeScript interfaces and enums
18
-
19
-
## Third Party
20
-
21
-
These plugins help reduce boilerplate associated with third-party dependencies. Hey API natively supports the most popular packages. Please open an issue on [GitHub](https://github.com/hey-api/openapi-ts/issues) if you'd like us to support your favorite package.
22
-
23
-
- [`@angular/common`](/openapi-ts/plugins/angular)
24
-
- [`@pinia/colada`](/openapi-ts/plugins/pinia-colada)
25
-
- [`@tanstack/angular-query-experimental`](/openapi-ts/plugins/tanstack-query)
26
-
- [`@tanstack/react-query`](/openapi-ts/plugins/tanstack-query)
27
-
- [`@tanstack/solid-query`](/openapi-ts/plugins/tanstack-query)
28
-
- [`@tanstack/svelte-query`](/openapi-ts/plugins/tanstack-query)
29
-
- [`@tanstack/vue-query`](/openapi-ts/plugins/tanstack-query)
30
-
- [`fastify`](/openapi-ts/plugins/fastify)
31
-
- [`valibot`](/openapi-ts/plugins/valibot)
32
-
- [`zod`](/openapi-ts/plugins/zod)
33
-
34
-
## Upcoming
35
-
36
-
The following plugins are planned but not in development yet. You can help us prioritize them by voting on [GitHub](https://github.com/hey-api/openapi-ts/labels/RSVP%20%F0%9F%91%8D%F0%9F%91%8E).
37
-
38
-
- [Adonis](/openapi-ts/plugins/adonis) <span data-soon>Soon</span>
39
-
- [Ajv](/openapi-ts/plugins/ajv) <span data-soon>Soon</span>
40
-
- [Arktype](/openapi-ts/plugins/arktype) <span data-soon>Soon</span>
41
-
- [Chance](/openapi-ts/plugins/chance) <span data-soon>Soon</span>
42
-
- [Express](/openapi-ts/plugins/express) <span data-soon>Soon</span>
43
-
- [Faker](/openapi-ts/plugins/faker) <span data-soon>Soon</span>
44
-
- [Falso](/openapi-ts/plugins/falso) <span data-soon>Soon</span>
45
-
- [Hono](/openapi-ts/plugins/hono) <span data-soon>Soon</span>
46
-
- [Joi](/openapi-ts/plugins/joi) <span data-soon>Soon</span>
47
-
- [Koa](/openapi-ts/plugins/koa) <span data-soon>Soon</span>
48
-
- [MSW](/openapi-ts/plugins/msw) <span data-soon>Soon</span>
49
-
- [Nest](/openapi-ts/plugins/nest) <span data-soon>Soon</span>
50
-
- [Nock](/openapi-ts/plugins/nock) <span data-soon>Soon</span>
51
-
- [Superstruct](/openapi-ts/plugins/superstruct) <span data-soon>Soon</span>
52
-
- [Supertest](/openapi-ts/plugins/supertest) <span data-soon>Soon</span>
53
-
- [SWR](/openapi-ts/plugins/swr) <span data-soon>Soon</span>
54
-
- [TypeBox](/openapi-ts/plugins/typebox) <span data-soon>Soon</span>
55
-
- [Yup](/openapi-ts/plugins/yup) <span data-soon>Soon</span>
56
-
- [Zustand](/openapi-ts/plugins/zustand) <span data-soon>Soon</span>
57
-
58
-
Don't see your plugin? [Build your own](/openapi-ts/plugins/custom) or let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues).
59
-
60
-
<!--@include: ../partials/examples.md-->
61
-
<!--@include: ../partials/sponsors.md-->
+4
docs/openapi-ts/plugins/custom.md
+4
docs/openapi-ts/plugins/custom.md
···
9
9
Plugin API is in 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).
10
10
:::
11
11
12
+
::: warning
13
+
This page is out of date as of [v0.83.0](/openapi-ts/migrating#v0-83-0). If you have an existing custom plugin, we recommend waiting for a more stable Plugin API to avoid multiple plugin rewrites.
14
+
:::
15
+
12
16
You may need to write your own plugin if the available plugins do not suit your needs or you're working on a proprietary use case. This can be easily achieved using the Plugin API. But don't take our word for it – all Hey API plugins are written this way!
13
17
14
18
## File Structure
+1
-1
docs/openapi-ts/plugins/valibot.md
+1
-1
docs/openapi-ts/plugins/valibot.md
+1
-1
docs/openapi-ts/plugins/zod.md
+1
-1
docs/openapi-ts/plugins/zod.md
+1
-1
docs/openapi-ts/plugins/zod/mini.md
+1
-1
docs/openapi-ts/plugins/zod/mini.md
+1
-1
docs/openapi-ts/plugins/zod/v3.md
+1
-1
docs/openapi-ts/plugins/zod/v3.md
docs/openapi-ts/transformers.md
docs/openapi-ts/plugins/transformers.md
docs/openapi-ts/transformers.md
docs/openapi-ts/plugins/transformers.md
+25
docs/vercel.json
+25
docs/vercel.json
···
15
15
"source": "/openapi-ts/custom-plugin",
16
16
"destination": "/openapi-ts/plugins/custom",
17
17
"permanent": true
18
+
},
19
+
{
20
+
"source": "/openapi-ts/plugins",
21
+
"destination": "/openapi-ts/core",
22
+
"permanent": true
23
+
},
24
+
{
25
+
"source": "/openapi-ts/output/json-schema",
26
+
"destination": "/openapi-ts/plugins/schemas",
27
+
"permanent": true
28
+
},
29
+
{
30
+
"source": "/openapi-ts/output/sdk",
31
+
"destination": "/openapi-ts/plugins/sdk",
32
+
"permanent": true
33
+
},
34
+
{
35
+
"source": "/openapi-ts/transformers",
36
+
"destination": "/openapi-ts/plugins/transformers",
37
+
"permanent": true
38
+
},
39
+
{
40
+
"source": "/openapi-ts/output/typescript",
41
+
"destination": "/openapi-ts/plugins/typescript",
42
+
"permanent": true
18
43
}
19
44
],
20
45
"trailingSlash": false