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, apiverse needs to generate TypeScript definitions from your OpenAPI schema files beforehand.

NOTE

TypeScript definitions with all OpenAPI schema types will be generated by apiverse. 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

apiverse 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 { resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { writeFile } from 'node:fs/promises'
import { defineEndpoints, generateDTS } from 'apiverse/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('apiverse.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 { OpenAPI, createClient } from 'apiverse'

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.