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 { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

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

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

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 { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerZod(
      {
        output: {
          path: './schemas',
        },
        group: { type: 'tag', output: './schemas/{{tag}}Schemas' },
      },
    ),
  ],
})

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 { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerZod(
      {
        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 { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerZod(
      {
        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 { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

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

typed

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

INFO

Type: boolean

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'
import createSwaggerTs from '@kubb/swagger-ts'

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

dateType

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

type

typescript
date: string
typescript
date: Date

INFO

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

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerZod({
      dateType: 'string',
    }),
  ],
})
typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

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

unknownType

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

type

typescript
any
typescript
unknown

INFO

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

typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerZod({
      unknownType: 'any',
    }),
  ],
})
typescript
import { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

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

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 { defineConfig } from '@kubb/core'
import createSwagger from '@kubb/swagger'
import createSwaggerZod from '@kubb/swagger-zod'

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

Depended

Released under the MIT License.