📘️ openapi-typescript-fetch

A typed fetch client for openapi-typescript

Install

1npm install openapi-typescript-fetch

Or

1yarn add openapi-typescript-fetch

Features

Supports JSON request and responses

• ✅ OpenAPI 3.0
• ✅ Swagger 2.0

Usage

Generate typescript definition from schema

1npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output petstore.ts
2
3# 🔭 Loading spec from https://petstore.swagger.io/v2/swagger.json…
4# 🚀 https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]

Typed fetch client

1import 'whatwg-fetch'
2
3import { Fetcher } from 'openapi-typescript-fetch'
4
5import { paths } from './petstore'
6
7// declare fetcher for paths
8const fetcher = Fetcher.for<paths>()
9
10// global configuration
11fetcher.configure({
12  baseUrl: 'https://petstore.swagger.io/v2',
13  init: {
14    headers: {
15      ...
16    },
17  },
18  use: [...] // middlewares
19})
20
21// create fetch operations
22const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create()
23const addPet = fetcher.path('/pet').method('post').create()
24
25// fetch
26const { status, data: pets } = await findPetsByStatus({
27  status: ['available', 'pending'],
28})
29
30console.log(pets[0])

Typed Error Handling

A non-ok fetch response throws a generic ApiError

But an Openapi document can declare a different response type for each status code, or a default error response type

These can be accessed via a discriminated union on status, as in code snippet below

1const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create()
2const addPet = fetcher.path('/pet').method('post').create()
3
4try {
5  await findPetsByStatus({ ... })
6  await addPet({ ... })
7} catch(e) {
8  // check which operation threw the exception
9  if (e instanceof addPet.Error) {
10    // get discriminated union { status, data }
11    const error = e.getActualType()
12    if (error.status === 400) {
13      error.data.validationErrors // only available for a 400 response
14    } else if (error.status === 500) {
15      error.data.errorMessage // only available for a 500 response
16    } else {
17      ...
18    }
19  }
20}

Middleware

Middlewares can be used to pre and post process fetch operations (log api calls, add auth headers etc)

1
2import { Middleware } from 'openapi-typescript-fetch'
3
4const logger: Middleware = async (url, init, next) => {
5  console.log(`fetching ${url}`)
6  const response = await next(url, init)
7  console.log(`fetched ${url}`)
8  return response
9}
10
11fetcher.configure({
12  baseUrl: 'https://petstore.swagger.io/v2',
13  init: { ... },
14  use: [logger],
15})
16
17// or
18
19fetcher.use(logger)

Server Side Usage

This library can be used server side with node-fetch

Node CommonJS setup

1// install node-fetch v2
2npm install node-fetch@2
3npm install @types/node-fetch@2
4
5// fetch-polyfill.ts
6import fetch, { Headers, Request, Response } from 'node-fetch'
7
8if (!globalThis.fetch) {
9    globalThis.fetch = fetch as any
10    globalThis.Headers = Headers as any
11    globalThis.Request = Request as any
12    globalThis.Response = Response as any
13}
14
15// index.ts
16import './fetch-polyfill'

Utility Types

• OpArgType - Infer argument type of an operation
• OpReturnType - Infer return type of an operation
• OpErrorType - Infer error type of an operation
• FetchArgType - Argument type of a typed fetch operation
• FetchReturnType - Return type of a typed fetch operation
• FetchErrorType - Error type of a typed fetch operation
• TypedFetch - Fetch operation type

1import { paths, operations } from './petstore'
2
3type Arg = OpArgType<operations['findPetsByStatus']>
4type Ret = OpReturnType<operations['findPetsByStatus']>
5type Err = OpErrorType<operations['findPetsByStatus']>
6
7type Arg = OpArgType<paths['/pet/findByStatus']['get']>
8type Ret = OpReturnType<paths['/pet/findByStatus']['get']>
9type Err = OpErrorType<paths['/pet/findByStatus']['get']>
10
11type FindPetsByStatus = TypedFetch<operations['findPetsByStatus']>
12
13const findPetsByStatus = fetcher
14  .path('/pet/findByStatus')
15  .method('get')
16  .create()
17
18type Arg = FetchArgType<typeof findPetsByStatus>
19type Ret = FetchReturnType<typeof findPetsByStatus>
20type Err = FetchErrorType<typeof findPetsByStatus>

Utility Methods

• arrayRequestBody - Helper to merge params when request body is an array see issue

1const body = arrayRequestBody([{ item: 1 }], { param: 2 })
2
3// body type is { item: number }[] & { param: number }

Long numeric values (de)serialization: BigInt

Stringifying and parsing big numeric values could be problematic. JSON.parse will coerce large numeric values and JSON.stringify will throw an error: Uncaught TypeError: Do not know how to serialize a BigInt in such cases.

To circumvent this issue, this library will serialize big numeric values to BigInt using JSON.rawJSON, and equally parse big numeric values from responses via JSON.parse source text access transforming them to BigInt for you.

If you rely on the precision of big number in responses, or are sending big numeric values, make sure your JavaScript environment supports it. Read below...

JavaScript engine/environment support

TL;DR

• Node 21
• Chrome 112

Support is conditional; the TC39 proposal has reached staged 3 and has even shipped with Chrome by default already, with the rest of modern browsers soon to follow with their corresponding releases.

Regarding Node.js support; at least Node 20 is required to be run with the next harmony flag node --harmony-json-parse-with-source (or Node 21 without flag 🎉), until it is switched by default in future versions.

---

Happy fetching! 👍