📘️ @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

``ps1
pnpm add @cuppachino/openapi-fetch
`

`ps1
npm i @cuppachino/openapi-fetch
`

`ps1
yarn add @cuppachino/openapi-fetch
`

$3

Supports JSON request and responses

* ✅ OpenAPI 3.0
* ✅ Swagger 2.0

Usage

$3

`bash
npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output petstore.ts

🔭 Loading spec from https://petstore.swagger.io/v2/swagger.json…

🚀 https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]

`

$3

`ts
import 'whatwg-fetch'

import { Fetcher } from '@cuppachino/openapi-fetch'

import { paths } from './petstore'

// declare fetcher for paths
const fetcher = Fetcher.for()

// global configuration
fetcher.configure({
baseUrl: 'https://petstore.swagger.io/v2',
init: {
headers: {
...
},
},
use: [...] // middlewares
})

// create fetch operations
const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create()
const addPet = fetcher.path('/pet').method('post').create()

// fetch
const { status, data: pets } = await findPetsByStatus({
status: ['available', 'pending'],
})

console.log(pets[0])
`

$3

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

`ts
const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create()
const addPet = fetcher.path('/pet').method('post').create()

try {
await findPetsByStatus({ ... })
await addPet({ ... })
} catch(e) {
// check which operation threw the exception
if (e instanceof addPet.Error) {
// get discriminated union { status, data }
const error = e.getActualType()
if (error.status === 400) {
error.data.validationErrors // only available for a 400 response
} else if (error.status === 500) {
error.data.errorMessage // only available for a 500 response
} else {
...
}
}
}
`

$3

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

`ts

import { Middleware } from '@cuppachino/openapi-fetch'

const logger: Middleware = async (url, init, next) => {
console.log(fetching ${url})
const response = await next(url, init)
console.log(fetched ${url})
return response
}

fetcher.configure({
baseUrl: 'https://petstore.swagger.io/v2',
init: { ... },
use: [logger],
})

// or

fetcher.use(logger)
`

$3

This library can be used server side with node-fetch

Node CommonJS setup

`ts
// install node-fetch v2
npm install node-fetch@2
npm install @types/node-fetch@2

// fetch-polyfill.ts
import fetch, { Headers, Request, Response } from 'node-fetch'

if (!globalThis.fetch) {
globalThis.fetch = fetch as any
globalThis.Headers = Headers as any
globalThis.Request = Request as any
globalThis.Response = Response as any
}

// index.ts
import './fetch-polyfill'
`

$3

* 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

`ts
import { paths, operations } from './petstore'

type Arg = OpArgType
type Ret = OpReturnType
type Err = OpErrorType

type Arg = OpArgType
type Ret = OpReturnType
type Err = OpErrorType

type FindPetsByStatus = TypedFetch

const findPetsByStatus = fetcher.path('/pet/findByStatus').method('get').create()

type Arg = FetchArgType
type Ret = FetchReturnType
type Err = FetchErrorType
`

$3

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

`ts

const body = arrayRequestBody([{ item: 1}], { param: 2})

// body type is { item: number }[] & { param: number }
``

Happy fetching! 👍