Skip to content

@kubb/swagger-zod 🦙

With the Swagger Zod plugin you can use Zod to validate your schema's based on a Swagger file.

Installation

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

Options

output

Relative path to save the Zod schemas. 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: 'zod'

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  output: {
    path: './zod',
  },
})

output.exportAs

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

INFO

Type: string

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  output: {
    path: './zod',
    exportAs: 'schemas',
  },
})

output.extName

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

INFO

Type: string

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  output: {
    path: './zod',
    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 { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  output: {
    path: './zod',
    exportType: 'barrel',
  },
})

group

Group the Zod schemas 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

TIP

When defining a custom output path, you should also update output.path to contain the same root path.

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

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

group.exportAs

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

Type: string
Default: '{{tag}}Schemas'

INFO

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  output: {
    path: './schemas'
  },
  group: { type: 'tag', output: './schemas/{{tag}}Schemas' },
})

typed

Use TypeScript(@kubb/swagger-ts) to add type annotation.

INFO

Type: boolean

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  typed: true,
})

typedSchema

Return Zod generated schema as type with z.infer.

INFO

Type: boolean

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  typedSchema: true,
})

dateType

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

TYPE

typescript
z.string()
typescript
z.string().datetime()
typescript
z.string().datetime({ offset: true })
typescript
z.string().datetime({ local: true })
typescript
z.date()

INFO

Type: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
Default: 'string'

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  dateType: 'string',
})

unknownType

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

TYPE

typescript
z.any()
typescript
z.unknown()

coercion

Use of z.coerce.string() instead of z.string(). Coercion for primitives

TYPE

typescript
z.coerce.string()
z.coerce.date()
z.coerce.number()
typescript
z.string()
z.date()
z.number()

INFO

Type: boolean
Default: false

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  coercion: true
})

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 { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  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 { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  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 { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  override: [
    {
      type: 'tag',
      pattern: 'pet',
      options: {
        dateType: 'stringOffset',
      },
    },
  ],
})

transformers

transformers.name

Override the name of the Zod schema that is getting generated, this will also override the name of the file.

INFO

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

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
  transformers: {
    name: (name) => {
      return `${name}Client`
    },
  },
})

importPath

Path to Zod. It will be used as import { z } from '${importPath}'. It allows both relative and absolute path. the path will be applied as is, so relative path should be based on the file being generated.

INFO

Type: string
Default: 'zod'

typescript
import { pluginZod } from '@kubb/swagger-zod'

const plugin = pluginZod({
 importPath: 'zod'
})

templates

Make it possible to override one of the templates.

TIP

See templates for more information about creating templates.
Set false to disable a template.

TYPE

typescript
import type { Operations } from '@kubb/swagger-zod/components'

export type Templates = {
  operations: typeof Operations.templates | false
}

INFO

Type: Templates

tsx
import { pluginZod } from '@kubb/swagger-zod'
import { Parser, File, Function } from '@kubb/react'
import { Operations } from '@kubb/swagger-zod/components'
import React from 'react'

export const templates = {
  ...Operations.templates,
} as const

const plugin = pluginZod({
  templates: {
    operations: templates,
  },
})

Example

typescript
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginZod } from '@kubb/swagger-zod'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    pluginOas(),
    pluginZod({
      output: {
        path: './zod',
      },
      group: { type: 'tag', output: './schemas/{{tag}}Schemas' },
      typed: true,
      dateType: 'stringOffset',
      unknownType: 'unknown',
      importPath: 'zod'
    }),
  ],
})

Released under the MIT License.