Kubb

Appearance

@kubb/swagger-msw 🦙 ​

TIP


MSW v2 is fully supported, see Migrating to MSW 2.0.0.

Just install v2 in your project and Kubb will check the package.json to see if you are using v1 or v2.

With the MSW plugin you can use MSW to create API mocks based on a Swagger file.

Installation ​

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

Options ​

output ​

output.path ​

Relative path to save the MSW 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 { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerFaker } from '@kubb/swagger-faker'
import { definePlugin as createSwaggerMsw } from '@kubb/swagger-msw'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

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

output.exportAs ​

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

INFO

Type: string

typescript
import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerFaker } from '@kubb/swagger-faker'
import { definePlugin as createSwaggerMsw } from '@kubb/swagger-msw'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerFaker({}),
    createSwaggerMsw(
      {
        output: {
          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 { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerFaker } from '@kubb/swagger-faker'
import { definePlugin as createSwaggerMsw } from '@kubb/swagger-msw'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

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

INFO

typescript
import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerFaker } from '@kubb/swagger-faker'
import { definePlugin as createSwaggerMsw } from '@kubb/swagger-msw'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerFaker({}),
    createSwaggerMsw(
      {
        output: {
          path: './mocks',
        },
        group: { type: 'tag', output: './mocks/{{tag}}Handlers' },
      },
    ),
  ],
})

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 { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerFaker } from '@kubb/swagger-faker'
import { definePlugin as createSwaggerMsw } from '@kubb/swagger-msw'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerFaker({}),
    createSwaggerMsw(
      {
        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 { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerFaker } from '@kubb/swagger-faker'
import { definePlugin as createSwaggerMsw } from '@kubb/swagger-msw'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerFaker({}),
    createSwaggerMsw(
      {
        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 { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerFaker } from '@kubb/swagger-faker'
import { definePlugin as createSwaggerMsw } from '@kubb/swagger-msw'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

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

transformers ​

transformers.name ​

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

INFO

Type: (name: string) => string

typescript
import { defineConfig } from '@kubb/core'
import { definePlugin as createSwagger } from '@kubb/swagger'
import { definePlugin as createSwaggerFaker } from '@kubb/swagger-faker'
import { definePlugin as createSwaggerMsw } from '@kubb/swagger-msw'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

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

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 { Handlers, Mock } from '@kubb/swagger-msw/components'

export type Templates = {
  handlers?: typeof Handlers.templates | false
  mock?: typeof Mock.templates | false
}

INFO

Type: Templates

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

import { templates } from './CustomTemplate'

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

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

Depended ​

Released under the MIT License.

Copyright © 2022-2024 Stijn Van Hulle