Skip to content
OpenAPI logo

OpenAPI

Officialv5.21.2

@kubb/adapter-oas

kubb add adapter-oas

Options

Pass these options to adapterOas(). All of them are optional.

Options overview

OptionPurposeDefault
Reading the spec
validateValidate the spec.true
contentTypeMedia type to keep.Every media type
serverServer that sets baseURL.None
Schema shape
discriminatorHow discriminators apply.'preserve'
enumsWhere inline enums live.'inline'
enumSuffixSuffix of enum names.'enum'
pathParamsCasingRename path parameters to camelCase.None
Type mapping
dateTypeType of date and time fields.'string'
integerTypeType of int64 and uint64 fields.'bigint'
unknownTypeType of open values.'unknown'
emptySchemaTypeType 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.

Typeboolean
Requiredfalse
Defaulttrue
OpenAPI 3.2 documents are not validated yet, and get one warning that says so.

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
Requiredfalse
DefaultEvery 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> }
Requiredfalse
DefaultNone, so baseURL is null
  • index: position in the servers array, usually 0.
  • variables: placeholder values. A variable you leave out uses its spec default.
// spec server: https://api.{env}.example.com
adapterOas({ server: { index: 0, variables: { env: 'prod' } } })
// baseURL: https://api.prod.example.com
Banners read this baseURL 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'
Requiredfalse
Default'preserve'
'preserve'
Keeps child schemas as written. The parent union still narrows each branch.
'propagate'
Also writes the discriminator literal into each child schema, so a child is narrowed on its own too.

enums

Where inline enums live. Names are the same in both modes.

Type'inline' | 'root'
Requiredfalse
Default'inline'
'inline'
Keeps each enum on the property that declares it.
'root'
Lifts every inline enum to a referenced top-level schema, such as 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;
};

enumSuffix

Suffix of inline enum names. The status enum on Pet becomes PetStatusEnum, or PetStatusType with enumSuffix: 'type'.

Typestring
Requiredfalse
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'
Requiredfalse
Defaultundefined

For GET /stores/{store-id}/pets/{pet-id}, @kubb/plugin-client generates:

await getPet({ path: { 'store-id': storeId, 'pet-id': 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.

Typefalse | 'string' | 'stringOffset' | 'stringLocal' | 'date' | { dateTime?, date?, time? }
Requiredfalse
Default'string'
'string'
Types all three as ISO 8601 strings.
false
Types all three as plain strings, with no format check.
'stringOffset'
Like 'string', with a timezone offset on date-time.
'stringLocal'
Like 'string', with no timezone on date-time.
'date'
Types all three as a JavaScript 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'
Requiredfalse
Default'bigint'
'bigint'
Keeps 64-bit IDs exact. JSON.stringify and JSON.parse cannot round-trip a bigint, so use it only when the app handles bigint serialization.
'number'
Fits most JSON APIs. Loses precision above 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'
Requiredfalse
Default'unknown'
'unknown'
Callers must narrow the value before they use it.
'any'
Callers can use the value without type checks.
'void'
Marks a value callers should not use, to match a legacy API.

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'
Requiredfalse
DefaultunknownType, so 'unknown' by default
Pair unknownType: 'unknown' with emptySchemaType: 'any' to keep empty 204 bodies easy to use.