Axios
Officialv6.2.0@kubb/plugin-axios
Call operations
Call a generated function with grouped request options, read the typed result, and pass content types or native axios settings for one call.
Call an operation
Pass each request part under its own key: path, query, headers, cookies, or body. A key exists only when the operation declares that part:
import { getPetById } from './gen/clients/getPetById'
import { updatePet } from './gen/clients/updatePet'
const { data } = await getPetById({ path: { petId: 1 } })
// ^ the parsed pet, typed from the 200 response
await updatePet({ path: { petId: 1 }, headers: { 'X-Request-ID': 'r-1' }, body: { name: 'Rex', status: 'sold' } })
await getStatus() // no required parameters, no argumentPath keys keep the spec's names, so {pet-id} takes path: { 'pet-id': 1 }. Set pathParamsCasing: 'camelcase' on the adapter (@kubb/adapter-oas 5.20.0 or later) to pass petId instead.
Read the result
A call resolves to a RequestResult, a union narrowed by the numeric status:
type RequestResult = {
status: number
data: TData // the parsed success body, undefined on an error result
error: TError // the parsed error body, undefined on a success result
contentType: string | undefined // the response media type, without parameters
headers: Headers // the response headers
request: AxiosRequestConfig // the native request config
response: AxiosResponse // the native response
}With the default throwOnError: true, a resolved call is always a success. Narrow on status when an operation has several success statuses:
const result = await getPetById({ path: { petId: 1 } })
console.info(result.headers.get('x-ratelimit-remaining')) // suggests the declared header names
if (result.status === 200) console.info(result.data)Unwrap the success body
Call .unwrap() to get only the success body:
const pet = await getPetById({ path: { petId: 1 } }).unwrap()
// ^ the parsed petthrowOnError | A non-2xx response makes .unwrap() |
|---|---|
true (default) | throw a ResponseError, as a plain await does. |
false | reject with the parsed error body. |
To get the body from every call, set returnType: 'data' on the plugin.
Set the content type
When an operation accepts or returns several content types, set contentType on the call. A string sets Content-Type, and response sets Accept:
await uploadAvatar({ path: { petId: 1 }, body: avatarBlob, contentType: 'image/png' })await getPet({ path: { petId: 1 }, contentType: { request: 'application/json', response: 'application/xml' } })Pass native axios options
Pass options for axios settings such as timeout, proxy, maxRedirects, decompress, or onUploadProgress:
await getPetById({ path: { petId: 1 }, options: { timeout: 5_000 } })client.setConfig({ options }) sets shared defaults, and per-call options win. Kubb keeps control of the URL, method, headers, body, and status handling, as Use a custom transport lists.
Build a URL without sending
client.getUrl builds the URL a request would use, with the same base URL and serialization:
import { client } from './gen/.kubb/client'
const url = client.getUrl({ url: '/pets/{petId}', path: { petId: 1 }, query: { fields: 'name' } })
// https://petstore.swagger.io/v2/pets/1?fields=nameNext, handle errors, including throwOnError: false.
Less common cases
Path parameter casing
When you set pathParamsCasing: 'camelcase', the HTTP request stays the same, because path parameter names never reach the wire. The exception is the matrix style, which sends the name (;group-id=42), so an operation with a matrix path parameter keeps its spec names.
