You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`data` and `error` are typechecked and expose their shapes to Intellisence in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch.
47
+
`data` and `error` are typechecked and expose their shapes to Intellisense in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch.
48
48
49
49
`GET()`, `PUT()`, `POST()`, etc. are thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for any call](/openapi-fetch/api#create-client)).
openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Weighs **4 kB** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS.
3
+
openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Weighs **5 kb** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS.
@@ -12,7 +12,7 @@ openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Wei
12
12
13
13
_\*[Benchmarks are approximate](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-fetch/test/index.bench.js) to just show rough baseline and will differ among machines and browsers. The relative performance between libraries is more reliable._
14
14
15
-
The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 2 kB package.
15
+
The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 5 kb package.
`data` and `error` are typechecked and expose their shapes to Intellisense in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch.
40
40
41
-
`GET`, `PUT`, `POST`, etc. are only thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for anycall](https://openapi-ts.dev/openapi-fetch/api/#create-client)).
41
+
`GET()`, `PUT()`, `POST()`, etc. are thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for anycall](https://openapi-ts.dev/openapi-fetch/api/#create-client)).
42
42
43
43
Notice there are no generics, and no manual typing. Your endpoint’s request and response were inferred automatically. This is a huge improvement in the type safety of your endpoints because **every manual assertion could lead to a bug**! This eliminates all of the following:
44
44
@@ -49,7 +49,7 @@ Notice there are no generics, and no manual typing. Your endpoint’s request an
49
49
- ✅ Also eliminates `as` type overrides that can also hide bugs
50
50
- ✅ All of this in a **5 kb** client package 🎉
51
51
52
-
## 🔧 Setup
52
+
## Setup
53
53
54
54
Install this library along with [openapi-typescript](../openapi-typescript):
55
55
@@ -58,17 +58,17 @@ npm i openapi-fetch
58
58
npm i -D openapi-typescript typescript
59
59
```
60
60
61
-
> **Highly recommended**: enable [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in your `tsconfig.json` ([docs](/advanced#enable-nouncheckedindexaccess-in-your-tsconfigjson))
61
+
> **Highly recommended**
62
+
>
63
+
> Enable [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in your `tsconfig.json` ([docs](/advanced#enable-nouncheckedindexaccess-in-your-tsconfigjson))
62
64
63
65
Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:
> ⚠️ Be sure to <ahref="https://redocly.com/docs/cli/commands/lint/"target="_blank"rel="noopener noreferrer">validate your schemas</a>! openapi-typescript will err on invalid schemas.
70
-
71
-
Lastly, be sure to **run typechecking** in your project. This can be done by adding `tsc --noEmit` to your <ahref="https://docs.npmjs.com/cli/v9/using-npm/scripts"target="_blank"rel="noopener noreferrer">npm scripts</a> like so:
71
+
Lastly, be sure to **run typechecking** in your project. This can be done by adding `tsc --noEmit` to your [npm scripts](https://docs.npmjs.com/cli/v9/using-npm/scripts) like so:
72
72
73
73
```json
74
74
{
@@ -80,9 +80,11 @@ Lastly, be sure to **run typechecking** in your project. This can be done by add
80
80
81
81
And run `npm run test:ts` in your CI to catch type errors.
82
82
83
-
> **Tip**: use `tsc --noEmit` to check for type errors rather than relying on your linter or your build command. Nothing will typecheck as accurately as the TypeScript compiler itself.
83
+
> **TIP:**
84
+
>
85
+
> Use `tsc --noEmit` to check for type errors rather than relying on your linter or your build command. Nothing will typecheck as accurately as the TypeScript compiler itself.
84
86
85
-
## Usage
87
+
## Basic usage
86
88
87
89
The best part about using openapi-fetch over oldschool codegen is no documentation needed. openapi-fetch encourages using your existing OpenAPI documentation rather than trying to find what function to import, or what parameters that function wants:
openapi-typescript generates TypeScript types from static <ahref="https://spec.openapis.org/oas/latest.html"target="_blank"rel="noopener noreferrer">OpenAPI</a> schemas quickly using only Node.js. It is fast, lightweight, (almost) dependency-free, and no Java/node-gyp/running OpenAPI servers necessary.
3
+
openapi-typescript turns [OpenAPI 3.0 & 3.1](https://spec.openapis.org/oas/latest.html) schemas into TypeScript quickly using Node.js. No Java/node-gyp/running OpenAPI servers necessary.
4
4
5
5
The code is [MIT-licensed](./LICENSE) and free for use.
6
6
7
+
> **Tip:**
8
+
> New to OpenAPI? Speakeasy’s [Intro to OpenAPI](https://www.speakeasyapi.dev/openapi) is an accessible guide to newcomers that explains the “why” and “how” of OpenAPI.
9
+
7
10
## Features
8
11
9
-
- ✅ Supports OpenAPI 3.0 and 3.1 (including advanced features like <ahref="https://spec.openapis.org/oas/v3.1.0#discriminator-object"target="_blank"rel="noopener noreferrer">discriminators</a>)
10
-
- ✅ Generate **runtime-free types** that outperform old-school codegen
12
+
- ✅ Supports OpenAPI 3.0 and 3.1 (including advanced features like [discriminators](https://spec.openapis.org/oas/v3.1.0#discriminator-object))
13
+
- ✅ Generate **runtime-free types** that outperform oldschool codegen
11
14
- ✅ Load schemas from YAML or JSON, locally or remotely
12
-
- ✅ Native Node.js code is fast and generates types within milliseconds
15
+
- ✅ Generate types for even huge schemas within milliseconds
16
+
17
+
_Note: OpenAPI 2.x is supported with versions `5.x` and previous_
13
18
14
19
## Examples
15
20
16
21
👀 [See examples](./examples/)
17
22
18
23
## Setup
19
24
20
-
This library requires the latest version of <ahref="https://nodejs.org/en"target="_blank"rel="noopener noreferrer">Node.js</a> installed (20.x or higher recommended). With that present, run the following in your project:
25
+
This library requires the latest version of [Node.js](https://nodejs.org) installed (20.x or higher recommended). With that present, run the following in your project:
21
26
22
27
```bash
23
28
npm i -D openapi-typescript typescript
24
29
```
25
30
26
-
> ✨ **Tip**
27
-
>
28
-
> Enabling [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in `tsconfig.json` can go along way to improve type safety ([read more](../../docs/src/content/docs/advanced.md#enable-nouncheckedindexedaccess-in-your-tsconfigjson))
31
+
And in your `tsconfig.json`, to load the types properly:
32
+
33
+
```diff
34
+
{
35
+
"compilerOptions": {
36
+
+ "module": "ESNext", // or "NodeNext"
37
+
+ "moduleResolution": "Bundler" // or "NodeNext"
38
+
}
39
+
}
40
+
```
41
+
42
+
> **Highly recommended**
43
+
>
44
+
> Also adding the following can boost type safety:
45
+
> ```diff
46
+
> {
47
+
> "compilerOptions": {
48
+
> + "noUncheckedIndexedAccess": true
49
+
> }
50
+
> }
51
+
> ```
29
52
30
53
## Basic usage
31
54
32
-
First, generate a local type file by running `npx openapi-typescript`:
55
+
First, generate a local type file by running `npx openapi-typescript`, first specifying your input schema (JSON or YAML), and where you’d like the `--output` (`-o`) to be saved:
> ⚠️ Be sure to <ahref="https://redocly.com/docs/cli/commands/lint/"target="_blank"rel="noopener noreferrer">validate your schemas</a>! openapi-typescript will err on invalid schemas.
47
-
48
-
Then, import schemas from the generated file like so:
67
+
Then in your TypeScript project, import types where needed:
49
68
50
69
```ts
51
70
importtype { paths, components } from"./my-openapi-3-schema"; // generated by openapi-typescript
0 commit comments