@onlycs/openapi-fetch

openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Weighs 6 kb and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS.

| Library | Size (min) | “GET” request\* |
| :------------------------- | ---------: | :------------------------- |
| openapi-fetch | 6 kB | 300k ops/s (fastest) |
| openapi-typescript-fetch | 3 kB | 300k ops/s (fastest) |
| feature-fetch | 15 kB | 300k ops/s (fastest) |
| axios | 32 kB | 225k ops/s (1.3× slower) |
| superagent | 55 kB | 50k ops/s (6× slower) |
| openapi-typescript-codegen | 367 kB | 100k ops/s (3× slower) |

_\* Benchmarks are approximate to just show rough baseline and will differ among machines and browsers. The relative performance between libraries is more reliable._

The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 6 kb package.

``ts
import createClient from "openapi-fetch";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const client = createClient({ baseUrl: "https://myapi.dev/v1/" });

const {
data, // only present if 2XX response
error, // only present if 4XX or 5XX response
} = await client.GET("/blogposts/{post_id}", {
params: {
path: { post_id: "123" },
},
});

await client.PUT("/blogposts", {
body: {
title: "My New Post",
},
});
`

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.

GET(), PUT(), POST(), etc. are thin wrappers around the native fetch API (which you can swap for any call).

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:

- ✅ No typos in URLs or params
- ✅ All parameters, request bodies, and responses are type-checked and 100% match your schema
- ✅ No manual typing of your API
- ✅ Eliminates any types that hide bugs
- ✅ Also eliminates as type overrides that can also hide bugs
- ✅ All of this in a 6 kb client package 🎉

Setup

Install this library along with openapi-typescript:

`bash
npm i openapi-fetch
npm i -D openapi-typescript typescript
`

> Highly recommended
>
> Enable noUncheckedIndexedAccess in your tsconfig.json (docs)

Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:

`bash
npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
`

Lastly, be sure to run typechecking in your project. This can be done by adding tsc --noEmit to your npm scripts like so:

`json
{
"scripts": {
"test:ts": "tsc --noEmit"
}
}
`

And run npm run test:ts in your CI to catch type errors.

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

Basic usage

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 schema example

`ts
import createClient from "openapi-fetch";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const client = createClient({ baseUrl: "https://myapi.dev/v1/" });

const { data, error } = await client.GET("/blogposts/{post_id}", {
params: {
path: { post_id: "my-post" },
query: { version: 2 },
},
});

const { data, error } = await client.PUT("/blogposts", {
body: {
title: "New Post",
body: "

New post body

",
publish_date: new Date("2023-03-01T12:00:00Z").getTime(),
},
});
`

1. The HTTP method is pulled directly from createClient()
2. You pass in your desired path to GET(), PUT()`, etc.
3. TypeScript takes over the rest and returns helpful errors for anything missing or invalid

📓 Docs

View Docs