mokkenstorm.dev
fork of hey-api/openapi-ts because I need some additional things
Merge pull request #229 from hey-api/fix/readme
fix(docs): ensure README is shown on NPMJS
authored by
Jordan Shatford
and committed by
GitHub
4978cc57
e0c794ad
+249
+5
.changeset/little-planets-camp.md
+5
.changeset/little-planets-camp.md
+244
packages/openapi-ts/README.md
+244
packages/openapi-ts/README.md
···
1
+
# OpenAPI TypeScript 👋
2
+
3
+
> ✨ Turn your OpenAPI specification into a beautiful TypeScript client
4
+
5
+
## Table of Contents
6
+
- [Table of Contents](#table-of-contents)
7
+
- [About](#about)
8
+
- [Features](#features)
9
+
- [Quick Start](#quick-start)
10
+
- [Installation](#installation)
11
+
- [Configuration](#configuration)
12
+
- [Clients](#clients)
13
+
- [Formatting](#formatting)
14
+
- [Linting](#linting)
15
+
- [Enums](#enums)
16
+
- [Config API](#config-api)
17
+
- [Interceptors](#interceptors)
18
+
- [Migrating](#migrating)
19
+
- [Contributing](#contributing)
20
+
21
+
## About
22
+
23
+
`openapi-ts` started as a fork of [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen). We created it after the original project became [unmaintained](https://github.com/ferdikoomen/openapi-typescript-codegen/issues/1276#issuecomment-1302392146) to add support for OpenAPI v3.1. We plan to resolve the most pressing issues in the original project – open an issue if you'd like to prioritise your use case!
24
+
25
+
## Features
26
+
27
+
- generate TypeScript clients from OpenAPI v2.0, v3.0, and v3.1 specifications
28
+
- support JSON or YAML input files
29
+
- handle external references using [JSON Schema $Ref Parser](https://github.com/APIDevTools/json-schema-ref-parser/)
30
+
- generate Fetch, Node-Fetch, Axios, Angular, or XHR HTTP clients
31
+
- can be used with CLI, Node.js, or npx
32
+
- abortable requests through cancellable promise pattern
33
+
34
+
## Quick Start
35
+
36
+
The fastest way to use `openapi-ts` is via npx
37
+
38
+
```sh
39
+
npx @hey-api/openapi-ts -i path/to/openapi.json -o src/client
40
+
```
41
+
42
+
Congratulations on creating your first client! 🎉
43
+
44
+
## Installation
45
+
46
+
```sh
47
+
npm install @hey-api/openapi-ts --save-dev
48
+
```
49
+
50
+
or
51
+
52
+
```sh
53
+
yarn add @hey-api/openapi-ts -D
54
+
```
55
+
56
+
or
57
+
58
+
```sh
59
+
pnpm add @hey-api/openapi-ts -D
60
+
```
61
+
62
+
If you want to use `openapi-ts` with CLI, add a script to your `package.json` file
63
+
64
+
```json
65
+
"scripts": {
66
+
"openapi-ts": "openapi-ts"
67
+
}
68
+
```
69
+
70
+
You can also generate your client programmatically by importing `openapi-ts` in a `.ts` file.
71
+
72
+
```ts
73
+
import { createClient } from '@hey-api/openapi-ts'
74
+
75
+
createClient({
76
+
input: 'path/to/openapi.json',
77
+
output: 'src/client',
78
+
})
79
+
```
80
+
81
+
> ⚠️ You need to be running Node.js v18 or newer
82
+
83
+
## Configuration
84
+
85
+
`openapi-ts` supports loading configuration from a file inside your project root directory. You can either create a `openapi-ts.config.cjs` file
86
+
87
+
```cjs
88
+
/** @type {import('@hey-api/openapi-ts').UserConfig} */
89
+
module.exports = {
90
+
input: 'path/to/openapi.json',
91
+
output: 'src/client',
92
+
}
93
+
```
94
+
95
+
or `openapi-ts.config.mjs`
96
+
97
+
```mjs
98
+
/** @type {import('@hey-api/openapi-ts').UserConfig} */
99
+
export default {
100
+
input: 'path/to/openapi.json',
101
+
output: 'src/client',
102
+
}
103
+
```
104
+
105
+
Alternatively, you can use `openapi-ts.config.js` and configure the export statement depending on your project setup.
106
+
107
+
### Clients
108
+
109
+
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
110
+
111
+
```mjs
112
+
/** @type {import('@hey-api/openapi-ts').UserConfig} */
113
+
export default {
114
+
client: 'fetch',
115
+
input: 'path/to/openapi.json',
116
+
output: 'src/client',
117
+
}
118
+
```
119
+
120
+
We support these clients:
121
+
122
+
- [angular](https://angular.io/) (using [RxJS](https://rxjs.dev/))
123
+
- [axios](https://axios-http.com/)
124
+
- [fetch](https://developer.mozilla.org/docs/Web/API/Fetch_API)
125
+
126
+
We also support the legacy Node.js and XHR clients:
127
+
128
+
- [node](https://nodejs.org/) (using [node-fetch](https://www.npmjs.com/package/node-fetch))
129
+
- [xhr](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest)
130
+
131
+
> ⚠️ You 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.
132
+
133
+
### Formatting
134
+
135
+
By default, `openapi-ts` will automatically format your client according to your project configuration. To disable automatic formatting, set `format` to false
136
+
137
+
```mjs
138
+
/** @type {import('@hey-api/openapi-ts').UserConfig} */
139
+
export default {
140
+
format: false,
141
+
input: 'path/to/openapi.json',
142
+
output: 'src/client',
143
+
}
144
+
```
145
+
146
+
You can also prevent your client from being processed by formatters by adding your output path to the tool's ignore file (e.g. `.prettierignore`).
147
+
148
+
### Linting
149
+
150
+
For performance reasons, `openapi-ts` does not automatically lint your client. To enable this feature, set `lint` to true
151
+
152
+
```mjs
153
+
/** @type {import('@hey-api/openapi-ts').UserConfig} */
154
+
export default {
155
+
input: 'path/to/openapi.json',
156
+
lint: true,
157
+
output: 'src/client',
158
+
}
159
+
```
160
+
161
+
You can also prevent your client from being processed by linters by adding your output path to the tool's ignore file (e.g. `.eslintignore`).
162
+
163
+
### Enums
164
+
165
+
If you need to iterate through possible field values without manually typing arrays, you can export enums with
166
+
167
+
```mjs
168
+
/** @type {import('@hey-api/openapi-ts').UserConfig} */
169
+
export default {
170
+
enums: 'javascript',
171
+
input: 'path/to/openapi.json',
172
+
output: 'src/client',
173
+
}
174
+
```
175
+
176
+
This will export enums as plain JavaScript objects. For example, `Foo` would become
177
+
178
+
```ts
179
+
export const FooEnum = {
180
+
FOO: 'foo',
181
+
BAR: 'bar',
182
+
} as const;
183
+
```
184
+
185
+
We discourage generating [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) because they are not standard JavaScript and pose [typing challenges](https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh). If you really need TypeScript enums, you can export them with
186
+
187
+
```mjs
188
+
/** @type {import('@hey-api/openapi-ts').UserConfig} */
189
+
export default {
190
+
enums: 'typescript',
191
+
input: 'path/to/openapi.json',
192
+
output: 'src/client',
193
+
}
194
+
```
195
+
196
+
### Config API
197
+
198
+
You can view the complete list of options in the [UserConfig](./src/types/config.ts) interface.
199
+
200
+
## Interceptors
201
+
202
+
Interceptors (middleware) can be used to modify requests before they're sent or responses before they're returned to the rest of your application. Below is an example request interceptor
203
+
204
+
```ts
205
+
OpenAPI.interceptors.request.use((request) => {
206
+
doSomethingWithRequest(request)
207
+
return request // <-- must return request
208
+
})
209
+
```
210
+
211
+
and an example response interceptor
212
+
213
+
```ts
214
+
OpenAPI.interceptors.response.use(async (response) => {
215
+
await doSomethingWithResponse(response) // async
216
+
return response // <-- must return response
217
+
})
218
+
```
219
+
220
+
If you need to remove an interceptor, pass the same function to `OpenAPI.interceptors.request.eject()` or `OpenAPI.interceptors.response.eject()`.
221
+
222
+
> ⚠️ Angular client does not currently support request interceptors.
223
+
224
+
## Migrating
225
+
226
+
While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features.
227
+
228
+
### v0.27.38
229
+
230
+
### `useOptions: true`
231
+
232
+
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.
233
+
234
+
```ts
235
+
import { DefaultService } from 'client' // <-- old client with array arguments
236
+
237
+
import { DefaultService } from 'client_v2' // <-- new client with options argument
238
+
```
239
+
240
+
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`.
241
+
242
+
## Contributing
243
+
244
+
Please refer to the [contributing guide](CONTRIBUTING.md) for how to install the project for development purposes.