OpenAPI
Officialv5.21.2@kubb/adapter-oas
Options
Pass these options to adapterOas(). All of them are optional.
Options overview
| Option | Purpose | Default |
|---|---|---|
| Reading the spec | ||
validate | Validate the spec. | true |
contentType | Media type to keep. | Every media type |
server | Server that sets baseURL. | None |
| Schema shape | ||
discriminator | How discriminators apply. | 'preserve' |
enums | Where inline enums live. | 'inline' |
enumSuffix | Suffix of enum names. | 'enum' |
pathParamsCasing | Rename path parameters to camelCase. | None |
| Type mapping | ||
dateType | Type of date and time fields. | 'string' |
integerType | Type of int64 and uint64 fields. | 'bigint' |
unknownType | Type of open values. | 'unknown' |
emptySchemaType | Type of empty schemas. | Same as unknownType |
Option details
Reading the spec
validate
Reports each spec problem as a KUBB_INVALID_SPEC warning, and generation continues. Set it to false to speed up a large spec. kubb validate lists every error.
| Type | boolean |
| Required | false |
| Default | true |
contentType
Media type to keep for request bodies and responses, also when an operation declares only one. A request body in another media type is dropped. A response in another media type gets emptySchemaType.
| Type | 'application/json' | string |
| Required | false |
| Default | Every media type |
server
Picks the servers entry that becomes the document baseURL, and fills in its {variable} placeholders.
| Type | { index?: number, variables?: Record<string, string> } |
| Required | false |
| Default | None, so baseURL is null |
index: position in theserversarray, usually0.variables: placeholder values. A variable you leave out uses its specdefault.
// spec server: https://api.{env}.example.com
adapterOas({ server: { index: 0, variables: { env: 'prod' } } })
// baseURL: https://api.prod.example.combaseURL as BannerMeta.baseURL, but it does not set request URLs. For those, set baseURL on @kubb/plugin-fetch, @kubb/plugin-axios, or @kubb/plugin-msw.Schema shape
discriminator
How discriminator fields on oneOf and anyOf schemas apply.
| Type | 'preserve' | 'propagate' |
| Required | false |
| Default | 'preserve' |
enums
Where inline enums live. Names are the same in both modes.
| Type | 'inline' | 'root' |
| Required | false |
| Default | 'inline' |
PetStatusEnum. A plugin that writes one file per schema gives it its own file.For a Pet.status enum, @kubb/plugin-ts writes:
// types/Pet.ts
export const petStatusEnum = {
active: 'active',
inactive: 'inactive',
} as const;
export type PetStatusEnumKey = (typeof petStatusEnum)[keyof typeof petStatusEnum];
export type Pet = {
status?: PetStatusEnumKey;
};// types/PetStatusEnum.ts
export const petStatusEnum = {
active: 'active',
inactive: 'inactive',
} as const;
export type PetStatusEnumKey = (typeof petStatusEnum)[keyof typeof petStatusEnum];
// types/Pet.ts
import type { PetStatusEnumKey } from './PetStatusEnum'
export type Pet = {
status?: PetStatusEnumKey;
};enumSuffix
Suffix of inline enum names. The status enum on Pet becomes PetStatusEnum, or PetStatusType with enumSuffix: 'type'.
| Type | string |
| Required | false |
| Default | 'enum' |
pathParamsCasing
Renames path parameters and their {placeholder} to camelCase, so {pet-id}, {pet_id}, and {PetId} become petId in clients, MSW routes, and query keys. The HTTP request and other parameters stay the same.
| Type | 'camelcase' |
| Required | false |
| Default | undefined |
For GET /stores/{store-id}/pets/{pet-id}, @kubb/plugin-client generates:
await getPet({ path: { 'store-id': storeId, 'pet-id': petId } })await getPet({ path: { storeId, petId } })An operation with a matrix path parameter keeps all its path parameter names, because a matrix value sends the name.
Type mapping
dateType
How date-time, date, and time schemas are typed. One value sets all three.
| Type | false | 'string' | 'stringOffset' | 'stringLocal' | 'date' | { dateTime?, date?, time? } |
| Required | false |
| Default | 'string' |
'string', with a timezone offset on date-time.'string', with no timezone on date-time.Date, which needs parsing to revive from JSON.To type each format on its own, pass an object. dateTime takes every value above, date and time take false, 'string', or 'date', and a key you leave out is 'string'.
integerType
How format: int64 and format: uint64 integers are typed. Other integers are always number.
| Type | 'number' | 'bigint' |
| Required | false |
| Default | 'bigint' |
JSON.stringify and JSON.parse cannot round-trip a bigint, so use it only when the app handles bigint serialization.Number.MAX_SAFE_INTEGER.unknownType
Type of a value the spec leaves open, such as the values of additionalProperties: {} or a parameter without a schema.
| Type | 'any' | 'unknown' | 'void' |
| Required | false |
| Default | 'unknown' |
emptySchemaType
Type of a schema with nothing to infer a type from, such as {} or a response without a schema. It takes the unknownType values.
| Type | 'any' | 'unknown' | 'void' |
| Required | false |
| Default | unknownType, so 'unknown' by default |
unknownType: 'unknown' with emptySchemaType: 'any' to keep empty 204 bodies easy to use.