📘️ @cuppachino/openapi-fetch

Changes from upstream

• ✅ Fixed ESM/CJS support for browsers and node.
• ✅ Zero-parameter requests do not require an empty object argument.

A typed fetch client for openapi-typescript

Installation

1pnpm add @cuppachino/openapi-fetch

1npm i @cuppachino/openapi-fetch

1yarn add @cuppachino/openapi-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 '@cuppachino/openapi-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 '@cuppachino/openapi-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.path('/pet/findByStatus').method('get').create()
14
15type Arg = FetchArgType<typeof findPetsByStatus>
16type Ret = FetchReturnType<typeof findPetsByStatus>
17type Err = FetchErrorType<typeof findPetsByStatus>

Utility Methods

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

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

Happy fetching! 👍