@kubb/swagger-client 🦙

With the Swagger client plugin you can create Axios API calls.

Installation

bun

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

pnpm

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

npm

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

yarn

yarn add @kubb/swagger-client @kubb/swagger-ts @kubb/swagger

Options

output

output.path

Output to save the clients.

INFO

Type: string
Default: 'clients'

kubb.config.js

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'

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

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 createSwaggerClient } from '@kubb/swagger-client'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

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

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 createSwaggerClient } from '@kubb/swagger-client'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({
      output: false,
    }),
    createSwaggerTS({}),
    createSwaggerClient({
      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 clients 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 clients. {{tag}} will be replaced by the current tagName.

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

group.exportAs

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

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

INFO

kubb.config.js

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'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: false }),
    createSwaggerTS({}),
    createSwaggerClient(
      {
        output: {
          path: './clients/axios',
        },
        group: { type: 'tag', output: './clients/axios/{{tag}}Service' },
      },
    ),
  ],
})

client

client.importPath

Path to the client import path that will be used to do the API calls.
It will be used as import client from '${client.importPath}'.
It allow both relative and absolute path. the path will be applied as is, so relative path shoule be based on the file being generated.

INFO

Type: string
Default: '@kubb/swagger-client/client'

kubb.config.js

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'

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

dataReturnType

ReturnType that needs to be used when calling client().

'data' will return ResponseConfig[data].
'full' will return ResponseConfig.

type

'data'

export async function getPetById<TData>(
  petId: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>["data"]> {
  ...
}

'full'

export async function getPetById<TData>(
  petId: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>> {
  ...
}

INFO

Type: 'data' | 'full'
Default: 'data'

'data'

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'

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

'full'

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'

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

pathParamsType

How to pass your pathParams.

'object' will return the pathParams as an object.
'inline' will return the pathParams as comma separated params.

type

'object'

export async function getPetById<TData>(
  { petId }: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>> {
  ...
}

'inline'

export async function getPetById<TData>(
  petId: GetPetByIdPathParams,
): Promise<ResponseConfig<TData>> {
  ...
}

INFO

Type: 'object' | 'inline'
Default: 'data'

'object'

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'

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

'inline'

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'

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

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 createSwaggerClient } from '@kubb/swagger-client'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

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

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

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

transformers

transformers.name

Override the name of the client 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 createSwaggerClient } from '@kubb/swagger-client'
import { definePlugin as createSwaggerTS } from '@kubb/swagger-ts'

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

import type { Client, Operations } from '@kubb/swagger-client/components'

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

INFO

Type: Templates

kubb.config.js

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 './CustomClientTemplate'

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

index.tsx

import { Editor, File, Function } from '@kubb/react'
import { Client } from '@kubb/swagger-client/components'
import type React from 'react'

export const templates = {
  ...Client.templates,
  default: function ({ name, generics, returnType, params, JSDoc, client }: React.ComponentProps<typeof Client.templates.default>) {
    const clientParams = [client.path.template, client.withData ? 'data' : undefined, 'options'].filter(Boolean).join(', ')

    return (
      <>
        <File.Import name="axios" path="axios" />
        <Function name={name} async export generics={generics} returnType={returnType} params={params} JSDoc={JSDoc}>
          {`return axios.${client.method}(${clientParams})`}
        </Function>
      </>
    )
  },
} as const

Depended

• @kubb/swagger
• @kubb/swagger-ts

Links

• Axios