Skip to content

@kubb/swagger-faker 🦙

With the Swagger Faker plugin, you can use Faker to create mocks based on a Swagger file.

Installation

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

Options

output

output.path

Relative path to save the Faker mocks. 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: 'mocks'

typescript
import { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  output: {
    path: './mocks',
  },
})

output.exportAs

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

INFO

Type: string

typescript
import { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  output: {
    path: './mocks',
    exportAs: 'mocks',
  },
})

output.extName

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

INFO

Type: string

typescript
import { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  output: {
    path: './mocks',
    extName: '.js',
  },
})

output.exportType

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

INFO

Type: 'barrel' | 'barrelNamed' | false

typescript
import { pluginFaker } from '@kubb/swagger-faker'

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

group

Group the Faker mocks 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 Faker mocks. {{tag}} will be replaced by the current tagName.

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

group.exportAs

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

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

INFO

typescript
import { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  group: {
    type: 'tag',
    output: './mocks/{{tag}}Mocks',
  },
})

dateType

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

TYPE

typescript
faker.string.alpha()
typescript
faker.date.anytime()

INFO

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

typescript
import { pluginFaker } from '@kubb/swagger-faker'

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

dateParser

Which parser should be used when dateType is set to 'string'.

TIP

You can use any other library. For example, when you want to use moment you can pass moment and Kubb will add the import for moment: import moment from 'moment'.

This only works when the package is using default exports like Dayjs and Moment.

TYPE

typescript
// schema with format set to 'date'
faker.date.anytime().toString()

// schema with format set to 'time'
faker.date.anytime().toString()
typescript
// schema with format set to 'date'
dayjs(faker.date.anytime()).format("YYYY-MM-DD")

// schema with format set to 'time'
dayjs(faker.date.anytime()).format("HH:mm:ss")
typescript
// schema with format set to 'date'
moment(faker.date.anytime()).format("YYYY-MM-DD")

// schema with format set to 'time'
moment(faker.date.anytime()).format("HH:mm:ss")

INFO

Type: 'dayjs' | 'moment' | string
Default: undefined

typescript
import { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  dateParser: 'dayjs',
})

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

const plugin = pluginFaker({
  unknownType: 'any',
})

seed

The use of Seed is intended to allow for consistent values in a test.

INFO

Type: 'number' | 'number[]'

typescript
import { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  seed: [222],
})

include

An 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 { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  include: [
    {
      type: 'tag',
      pattern: 'store',
    },
  ],
})

exclude

An 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 { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  exclude: [
    {
      type: 'tag',
      pattern: 'store',
    },
  ],
})

override

An 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 { pluginFaker } from '@kubb/swagger-faker'

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

transformers

transformers.name

Override the name of the faker data that is getting generated, this will also override the name of the file.

INFO

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

typescript
import { pluginFaker } from '@kubb/swagger-faker'

const plugin = pluginFaker({
  transformers: {
    name: (name) => {
      return `${name}Mock`
    },
  },
})

Example

typescript
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginFaker} from '@kubb/swagger-faker'
import { pluginTs } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginFaker({
      output: {
        path: './mocks',
      },
      group: {
        type: 'tag',
        output: './mocks/{{tag}}Mocks',
      },
      dateType: 'date',
      unknownType: 'unknown',
      seed: [100],
    }),
  ],
})

Released under the MIT License.