@kubb/swagger-ts 🦙

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

Installation

bun

bun add @kubb/swagger-ts @kubb/swagger

pnpm

pnpm add @kubb/swagger-ts @kubb/swagger

npm

npm install @kubb/swagger-ts @kubb/swagger

yarn

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'

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      output: {
        path: './models',
      },
    }),
  ],
})

output.exportAs

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

INFO

Type: string

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      output: {
        exportAs: 'models',
      },
    }),
  ],
})

output.extName

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

INFO

Type: string

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      output: {
        extName: '.js',
      },
    }),
  ],
})

output.exportType

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

INFO

Type: 'barrel' | 'barrelNamed' | false

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

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      output: {
        path: './types',
      },
      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

'enum'

enum PetType {
  Dog = 'dog',
  Cat = 'cat',
}

'asConst'

const petType = {
  Dog: 'dog',
  Cat: 'cat',
} as const

'asPascalConst'

const PetType = {
  Dog: 'dog',
  Cat: 'cat',
} as const

'constEnum'

const enum PetType {
  Dog = 'dog',
  Cat = 'cat',
}

'literal'

type PetType = 'dog' | 'cat'

INFO

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

'enum'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      enumType: 'enum',
    }),
  ],
})

'asConst'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      enumType: 'asConst',
    }),
  ],
})

'asPascalConst'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      enumType: 'asPascalConst',
    }),
  ],
})

'constEnum'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      enumType: 'constEnum',
    }),
  ],
})

'literal'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      enumType: 'literal',
    }),
  ],
})

enumSuffix

Set a suffix for the generated enums.

Type

INFO

Type: string
Default: ''

typescript

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      enumSuffix: 'enum',
    }),
  ],
})

dateType

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

type

'string'

date: string

'date'

date: Date

INFO

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

'string'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      dateType: 'string',
    }),
  ],
})

'date'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      dateType: 'date',
    }),
  ],
})

unknownType

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

type

'any'

any

'unknown'

unknown

INFO

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

'any'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      unknownType: 'any',
    }),
  ],
})

'unknown'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      unknownType: 'unknown',
    }),
  ],
})

optionalType

Choose what to use as mode for an optional value.

type

'questionToken'

type?: string

'undefined'

type: string | undefined

'questionTokenAndUndefined'

type?: string | undefined

INFO

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

'questionToken'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      optionalType: 'questionToken',
    }),
  ],
})

'undefined'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      optionalType: 'undefined',
    }),
  ],
})

'questionTokenAndUndefined'

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      optionalType: 'questionTokenAndUndefined',
    }),
  ],
})

include

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

type

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

INFO

Type: Array<Include>

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS(
      {
        include: [
          {
            type: 'tag',
            pattern: 'store',
          },
        ],
      },
    ),
  ],
})

exclude

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

type

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

INFO

Type: Array<Exclude>

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS(
      {
        exclude: [
          {
            type: 'tag',
            pattern: 'store',
          },
        ],
      },
    ),
  ],
})

override

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

type

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

INFO

Type: Array<Override>

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS(
      {
        override: [
          {
            type: 'tag',
            pattern: 'pet',
            options: {
              output: {
                path: './custom',
              },
            },
          },
        ],
      },
    ),
  ],
})

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

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS(
      {
        transformers: {
          name: (name) => {
            return `${name}Client`
          },
        },
      },
    ),
  ],
})

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

kubb.config.js

import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({
      oasType: 'infer',
    }),
  ],
})

Depended

• @kubb/swagger

Links

• TypeScript
• TypeScript Compiler API