Skip to content

Commit 972a93a

Browse files
mrlubosmrlubos
committed
feat: move everything into plugins
1 parent 245c37a commit 972a93a

File tree

170 files changed

+24957
-25775
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

170 files changed

+24957
-25775
lines changed

‎.changeset/blue-bikes-approve.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
'@hey-api/openapi-ts': minor
3+
'@hey-api/docs': minor
4+
---
5+
6+
feat: make plugins first-class citizens
7+
8+
This release makes plugins first-class citizens. In order to achieve that, the following breaking changes were introduced.
9+
10+
### Removed CLI options
11+
12+
The `--types`, `--schemas`, and `--services` CLI options have been removed. You can list which plugins you'd like to use explicitly by passing a list of plugins as `--plugins <plugin1> <plugin2>`
13+
14+
### Removed `*.export` option
15+
16+
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.
17+
18+
::: code-group
19+
20+
```js [shorthand]
21+
export default {
22+
client: '@hey-api/client-fetch',
23+
input: 'path/to/openapi.json',
24+
output: 'src/client',
25+
schemas: false, // [!code --]
26+
plugins: ['@hey-api/types', '@hey-api/services'], // [!code ++]
27+
};
28+
```
29+
30+
```js [*.export]
31+
export default {
32+
client: '@hey-api/client-fetch',
33+
input: 'path/to/openapi.json',
34+
output: 'src/client',
35+
schemas: {
36+
export: false, // [!code --]
37+
},
38+
plugins: ['@hey-api/types', '@hey-api/services'], // [!code ++]
39+
};
40+
```
41+
42+
:::
43+
44+
### Renamed `schemas.name` option
45+
46+
Each plugin definition contains a `name` field. This was conflicting with the `schemas.name` option. As a result, it has been renamed to `nameBuilder`.
47+
48+
```js
49+
export default {
50+
client: '@hey-api/client-fetch',
51+
input: 'path/to/openapi.json',
52+
output: 'src/client',
53+
schemas: {
54+
name: (name) => `${name}Schema`, // [!code --]
55+
},
56+
plugins: [
57+
// ...other plugins
58+
{
59+
nameBuilder: (name) => `${name}Schema`, // [!code ++]
60+
name: '@hey-api/schemas',
61+
},
62+
],
63+
};
64+
```
65+
66+
### Removed `services.include` shorthand option
67+
68+
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.
69+
70+
```js
71+
export default {
72+
client: '@hey-api/client-fetch',
73+
input: 'path/to/openapi.json',
74+
output: 'src/client',
75+
services: '^MySchema', // [!code --]
76+
plugins: [
77+
// ...other plugins
78+
{
79+
include: '^MySchema', // [!code ++]
80+
name: '@hey-api/services',
81+
},
82+
],
83+
};
84+
```
85+
86+
### Renamed `services.name` option
87+
88+
Each plugin definition contains a `name` field. This was conflicting with the `services.name` option. As a result, it has been renamed to `serviceNameBuilder`.
89+
90+
```js
91+
export default {
92+
client: '@hey-api/client-fetch',
93+
input: 'path/to/openapi.json',
94+
output: 'src/client',
95+
services: {
96+
name: '{{name}}Service', // [!code --]
97+
},
98+
plugins: [
99+
// ...other plugins
100+
{
101+
serviceNameBuilder: '{{name}}Service', // [!code ++]
102+
name: '@hey-api/services',
103+
},
104+
],
105+
};
106+
```
107+
108+
### Renamed `types.dates` option
109+
110+
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.
111+
112+
```js
113+
export default {
114+
client: '@hey-api/client-fetch',
115+
input: 'path/to/openapi.json',
116+
output: 'src/client',
117+
types: {
118+
dates: 'types+transform', // [!code --]
119+
},
120+
plugins: [
121+
// ...other plugins
122+
{
123+
dates: true, // [!code ++]
124+
name: '@hey-api/transformers',
125+
},
126+
],
127+
};
128+
```
129+
130+
### Removed `types.include` shorthand option
131+
132+
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.
133+
134+
```js
135+
export default {
136+
client: '@hey-api/client-fetch',
137+
input: 'path/to/openapi.json',
138+
output: 'src/client',
139+
types: '^MySchema', // [!code --]
140+
plugins: [
141+
// ...other plugins
142+
{
143+
include: '^MySchema', // [!code ++]
144+
name: '@hey-api/types',
145+
},
146+
],
147+
};
148+
```
149+
150+
### Renamed `types.name` option
151+
152+
Each plugin definition contains a `name` field. This was conflicting with the `types.name` option. As a result, it has been renamed to `style`.
153+
154+
```js
155+
export default {
156+
client: '@hey-api/client-fetch',
157+
input: 'path/to/openapi.json',
158+
output: 'src/client',
159+
types: {
160+
name: 'PascalCase', // [!code --]
161+
},
162+
plugins: [
163+
// ...other plugins
164+
{
165+
name: '@hey-api/types',
166+
style: 'PascalCase', // [!code ++]
167+
},
168+
],
169+
};
170+
```

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ layout: home
33

44
hero:
55
name: High-quality tools for interacting with APIs
6-
tagline: Codegen for your TypeScript projects. Trusted more than 500k times each month to generate reliable API clients and SDKs.
6+
tagline: Codegen for your TypeScript projects. Trusted more than 600k times each month to generate reliable API clients and SDKs.
77
actions:
88
- theme: brand
99
text: Get Started

‎docs/openapi-ts/configuration.md‎

Lines changed: 48 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Configure @hey-api/openapi-ts.
55

66
# Configuration
77

8-
`@hey-api/openapi-ts` supports loading configuration from any file inside your project root directory supported by [jiti loader](https://github.com/unjs/c12?tab=readme-ov-file#-features). Below are the most common file formats.
8+
`@hey-api/openapi-ts` supports loading configuration from any file inside your project root folder supported by [jiti loader](https://github.com/unjs/c12?tab=readme-ov-file#-features). Below are the most common file formats.
99

1010
::: code-group
1111

@@ -41,128 +41,25 @@ export default {
4141

4242
Alternatively, you can use `openapi-ts.config.js` and configure the export statement depending on your project setup.
4343

44-
## Clients
45-
46-
Clients are responsible for sending the actual HTTP requests. Apart from input and output, this is the only required option.
47-
48-
You can learn more on the [Clients](/openapi-ts/clients) page.
49-
50-
<!--
51-
TODO: uncomment after c12 supports multiple configs
52-
see https://github.com/unjs/c12/issues/92
53-
-->
54-
<!-- ### Multiple Clients
55-
56-
If you want to generate multiple clients with a single `openapi-ts` command, you can provide an array of configuration objects.
57-
58-
```js
59-
import { defineConfig } from '@hey-api/openapi-ts';
60-
61-
export default defineConfig([
62-
{
63-
client: 'legacy/fetch',
64-
input: 'path/to/openapi_one.json',
65-
output: 'src/client_one',
66-
},
67-
{
68-
client: 'legacy/axios',
69-
input: 'path/to/openapi_two.json',
70-
output: 'src/client_two',
71-
},
72-
])
73-
``` -->
74-
75-
## Services
44+
## Input
7645

77-
Services are abstractions on top of clients and serve the same purpose. By default, `@hey-api/openapi-ts` will generate a flat service layer. Your choice to use services comes down to personal preferences and bundle size considerations.
78-
79-
You can learn more on the [Output](/openapi-ts/output#api-services) page.
80-
81-
## Enums
82-
83-
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 `types.enums` to a valid option.
84-
85-
::: code-group
86-
87-
```js [disabled]
88-
export default {
89-
client: '@hey-api/client-fetch',
90-
input: 'path/to/openapi.json',
91-
output: 'src/client',
92-
types: {
93-
enums: false, // [!code ++]
94-
},
95-
};
96-
```
97-
98-
```js [javascript]
99-
export default {
100-
client: '@hey-api/client-fetch',
101-
input: 'path/to/openapi.json',
102-
output: 'src/client',
103-
types: {
104-
enums: 'javascript', // [!code ++]
105-
},
106-
};
107-
```
108-
109-
```js [typescript]
110-
export default {
111-
client: '@hey-api/client-fetch',
112-
input: 'path/to/openapi.json',
113-
output: 'src/client',
114-
types: {
115-
enums: 'typescript', // [!code ++]
116-
},
117-
};
118-
```
46+
Input is the first thing you must define. It can be a local path, remote URL, or a string content resolving to an OpenAPI specification. Hey API supports all valid OpenAPI versions and file formats.
11947

48+
::: info
49+
We use [`@apidevtools/json-schema-ref-parser`](https://github.com/APIDevTools/json-schema-ref-parser) to resolve file locations. Please note that accessing a HTTPS URL on localhost has a known [workaround](https://github.com/hey-api/openapi-ts/issues/276).
12050
:::
12151

122-
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).
52+
## Output
12353

124-
## JSON Schemas
125-
126-
By default, `@hey-api/openapi-ts` generates schemas from your OpenAPI specification. A great use case for schemas is client-side form input validation. If you're using OpenAPI 3.1, your [schemas](/openapi-ts/output#json-schemas) are JSON Schema compliant and can be used with other tools supporting JSON Schema. However, if you only want to validate form input, you probably don't want to include string descriptions inside your bundle. You can choose your preferred type using `schemas.type` option.
127-
128-
::: code-group
129-
130-
```js [json]
131-
export default {
132-
client: '@hey-api/client-fetch',
133-
input: 'path/to/openapi.json',
134-
output: 'src/client',
135-
schemas: {
136-
type: 'json', // [!code ++]
137-
},
138-
};
139-
```
140-
141-
```js [form]
142-
export default {
143-
client: '@hey-api/client-fetch',
144-
input: 'path/to/openapi.json',
145-
output: 'src/client',
146-
schemas: {
147-
type: 'form', // [!code ++]
148-
},
149-
};
150-
```
151-
152-
```js [disabled]
153-
export default {
154-
client: '@hey-api/client-fetch',
155-
input: 'path/to/openapi.json',
156-
output: 'src/client',
157-
schemas: false, // [!code ++]
158-
};
159-
```
54+
Output is the next thing to define. It can be either a string pointing to the destination folder or a configuration object containing the destination folder path and optional settings (these are described below).
16055

56+
::: tip
57+
You should treat the output folder as a dependency. Do not directly modify its contents as your changes might be erased when you run `@hey-api/openapi-ts` again.
16158
:::
16259

16360
## Formatting
16461

165-
By default, `@hey-api/openapi-ts` will not automatically format your output. To enable this feature, set `output.format` to a valid formatter.
62+
To format your output folder contents, set `output.format` to a valid formatter.
16663

16764
::: code-group
16865

@@ -205,7 +102,7 @@ You can also prevent your output from being formatted by adding your output path
205102

206103
## Linting
207104

208-
By default, `@hey-api/openapi-ts` will not automatically lint your output. To enable this feature, set `output.lint` to a valid linter.
105+
To lint your output folder contents, set `output.lint` to a valid linter.
209106

210107
::: code-group
211108

@@ -246,6 +143,43 @@ export default {
246143

247144
You can also prevent your output from being linted by adding your output path to the linter's ignore file.
248145

146+
## Clients
147+
148+
Clients are responsible for sending the actual HTTP requests. The `client` value is not required, but you must define it if you're generating the service layer (enabled by default).
149+
150+
You can learn more on the [Clients](/openapi-ts/clients) page.
151+
152+
<!--
153+
TODO: uncomment after c12 supports multiple configs
154+
see https://github.com/unjs/c12/issues/92
155+
-->
156+
<!-- ### Multiple Clients
157+
158+
If you want to generate multiple clients with a single `openapi-ts` command, you can provide an array of configuration objects.
159+
160+
```js
161+
import { defineConfig } from '@hey-api/openapi-ts';
162+
163+
export default defineConfig([
164+
{
165+
client: 'legacy/fetch',
166+
input: 'path/to/openapi_one.json',
167+
output: 'src/client_one',
168+
},
169+
{
170+
client: 'legacy/axios',
171+
input: 'path/to/openapi_two.json',
172+
output: 'src/client_two',
173+
},
174+
])
175+
``` -->
176+
177+
## Plugins
178+
179+
Plugins are responsible for generating artifacts from your input. By default, Hey API will generate TypeScript interfaces, JSON Schemas, and services from your OpenAPI specification. You can add, remove, or customize any of the plugins. In fact, we highly encourage you to do so!
180+
181+
You can learn more on the [Output](/openapi-ts/output) page.
182+
249183
## Config API
250184

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

‎docs/openapi-ts/get-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ import { embedProject } from '../embed'
1313
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).
1414
:::
1515

16-
[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) is an OpenAPI to TypeScript codegen trusted more than 500k 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 600k times each month to generate reliable API clients and SDKs.
1717

1818
<button class="buttonLink" @click="(event) => embedProject('hey-api-example')(event)">
1919
Live demo

0 commit comments

Comments
 (0)