OpenAPI
The OpenAPI adapter adds type-safety for API calls based on an OpenAPI schema. This includes path names, supported HTTP methods, request body, response body, query parameters, and headers.
In order to use this adapter, apiful
needs to generate TypeScript definitions from your OpenAPI schema files beforehand.
NOTE
TypeScript definitions with all OpenAPI schema types will be generated by apiful
. Make sure to save it as a .d.ts
file in your project and reference it in your tsconfig.json
file, if it is not included by default.
Schema Generation
apiful
provides a generateDTS
function that generates a TypeScript definitions file, which you have to save to the proper destination in your project.
Take this prepare.ts
file as an example:
import { writeFile } from 'node:fs/promises'
import { resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineEndpoints, generateDTS } from 'apiful/openapi'
const currentDir = fileURLToPath(new URL('.', import.meta.url))
export const endpoints = defineEndpoints({
petStore: {
// See: https://petstore3.swagger.io/api/v3/openapi.json
schema: resolve(currentDir, 'schemas/pet-store.json'),
},
})
const types = await generateDTS(endpoints)
await writeFile('apiful.d.ts', types)
NOTE
The openapi-typescript
library is used to generate the TypeScript definitions. It is a direct dependency and will become a peer dependency again when v7 public is released.
Using the OpenAPI
Adapter
After you have generated the TypeScript definitions file, you can use the OpenAPI
adapter to add type-safety to your API calls:
import { createClient, OpenAPI } from 'apiful'
const baseURL = 'https://petstore3.swagger.io/api/v3'
const adapter = OpenAPI<'petStore'>()
const petStore = createClient({ baseURL }).with(adapter)
// The response is typed based on the OpenAPI spec
const userResponse = await petStore('/user/{username}', {
method: 'GET',
path: { username: 'user1' },
})
console.log(userResponse)
The response returned by the API call on the left is typed as follows:
declare const userResponse: {
id?: number
username?: string
firstName?: string
lastName?: string
email?: string
password?: string
phone?: string
userStatus?: number
}
OpenAPI Path Parameters
OpenAPI can define path parameters on given endpoints. They are typically declared as /foo/{id}
. Unfortunately, the endpoint type is not defined as /foo/10
. Thus, using the latter as the path will break type inference.
Instead, use the property path
to pass an object of the parameters. You can then use the declared path for type inference, and the type checker will ensure you provide all required path parameters. The parameters will be interpolated into the path before the request is made.
const response = await petStore('/foo/{id}', {
path: {
id: 10,
},
})
WARNING
Incorrect parameters will not be reported at runtime. An incomplete path will be sent to the backend as-is.