Skip to content

@kubb/swagger-ts 🦙

With the Swagger TypeScript plugin you can create TypeScript types based on a Swagger file.

Installation

shell
bun add @kubb/swagger-ts @kubb/swagger
shell
pnpm add @kubb/swagger-ts @kubb/swagger
shell
npm install @kubb/swagger-ts @kubb/swagger
shell
yarn add @kubb/swagger-ts @kubb/swagger

Options

output

output.path

Relative path to save the TypeScript types.
When output is a file it will save all models inside that file else it will create a file per schema item.

INFO

Type: string
Default: 'types'

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
output
: {
path
: './models',
}, })

output.exportAs

Name to be used for the export * as from './'

INFO

Type: string

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
output
: {
path
: './models',
exportAs
: 'models',
}, })

output.extName

Add an extension to the generated imports and exports, default it will not use an extension

INFO

Type: string

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
output
: {
path
: './models',
extName
: '.js',
}, })

output.exportType

Define what needs to exported, here you can also disable the export of barrel files

INFO

Type: 'barrel' | 'barrelNamed' | false

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
output
: {
path
: './types',
exportType
: 'barrel',
}, })

group

Group the TypeScript types based on the provided name.

group.type

Tag will group based on the operation tag inside the Swagger file.

Type: 'tag'
Required: true

group.output

Relative path to save the grouped TypeScript Types. {{tag}} will be replaced by the current tagName.

Type: string
Example: models/{{tag}}Controller => models/PetController
Default: '${output}/{{tag}}Controller'

INFO

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
group
: {
type
: 'tag',
output
: './types/{{tag}}Controller' },
})

enumType

Choose to use enum or as const for enums.
asConst will use camelCase for the naming.
asPascalConst will use PascalCase for the naming.

TYPE

typescript
enum PetType {
  Dog = 'dog',
  Cat = 'cat',
}
typescript
const petType = {
  Dog: 'dog',
  Cat: 'cat',
} as const
typescript
const PetType = {
  Dog: 'dog',
  Cat: 'cat',
} as const
typescript
const enum PetType {
  Dog = 'dog',
  Cat = 'cat',
}
typescript
type PetType = 'dog' | 'cat'

INFO

Type: 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal'
Default: 'asConst'

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
enumType
: 'enum',
})

enumSuffix

Set a suffix for the generated enums.

TYPE

INFO

Type: string
Default: ''

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
enumSuffix
: 'Enum',
})

dateType

Choose to use date or datetime as JavaScript Date instead of string.

TYPE

typescript
type Pet = {
  date: string
}
typescript
type Pet = {
  date: Date
}

INFO

Type: 'string' | 'date'
Default: 'string'

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
dateType
: 'string',
})

unknownType

Which type to use when the Swagger/OpenAPI file is not providing more information.

TYPE

typescript
type Pet = {
  name: any
}
typescript
type Pet = {
  name: unknown
}

INFO

Type: 'any' | 'unknown'
Default: 'any'

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
unknownType
: 'any',
})

optionalType

Choose what to use as mode for an optional value.

TYPE

typescript
type Pet = {
  type?: string
}
typescript
type Pet = {
  type: string | undefined
}
typescript
type Pet = {
  type?: string | undefined
}

INFO

Type: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
Default: 'questionToken'

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
optionalType
: 'questionToken',
})

oasType

Export an Oas object as Oas type with import type { Infer } from '@kubb/swagger-ts/oas'
See infer in how to use the types with @kubb/swagger-ts/oas.

INFO

Type: 'infer' | false

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
oasType
: 'infer',
})

include

Array containing include parameters to include tags/operations/methods/paths.

TYPE

typescript
export type Include = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  pattern: string | RegExp
}

INFO

Type: Array<Include>

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
include
: [
{
type
: 'tag',
pattern
: 'store',
}, ], })

exclude

Array containing exclude parameters to exclude/skip tags/operations/methods/paths.

TYPE

typescript
export type Exclude = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  pattern: string | RegExp
}

INFO

Type: Array<Exclude>

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
exclude
: [
{
type
: 'tag',
pattern
: 'store',
}, ], })

override

Array containing override parameters to override options based on tags/operations/methods/paths.

TYPE

typescript
export type Override = {
  type: 'tag' | 'operationId' | 'path' | 'method'
  pattern: string | RegExp
  options: PluginOptions
}

INFO

Type: Array<Override>

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
override
: [
{
type
: 'tag',
pattern
: 'pet',
options
: {
enumType
: "asConst"
}, }, ], })

transformers

transformers.name

Override the name of the TypeScript type that is getting generated, this will also override the name of the file.

INFO

Type: (name: string, type?: "function" | "type" | "file" ) => string

typescript
import { 
pluginTs
} from '@kubb/swagger-ts'
const
plugin
=
pluginTs
({
transformers
: {
name
: (
name
) => {
return `${
name
}Client`
}, }, })

Example

typescript
import { 
defineConfig
} from '@kubb/core'
import {
pluginOas
} from '@kubb/plugin-oas'
import {
pluginTs
} from '@kubb/swagger-ts'
export default
defineConfig
({
input
: {
path
: './petStore.yaml',
},
output
: {
path
: './src/gen',
},
plugins
: [
pluginOas
(),
pluginTs
({
output
: {
path
: './types',
},
exclude
: [
{
type
: 'tag',
pattern
: 'store',
}, ],
group
: {
type
: 'tag',
output
: './types/{{tag}}Controller'
},
enumType
: "asConst",
enumSuffix
: 'Enum',
dateType
: 'date',
unknownType
: 'unknown',
optionalType
: 'questionTokenAndUndefined',
oasType
: false,
}), ], })

Released under the MIT License.