Skip to content

@kubb/swagger-swr 🦙

With the Swagger SWR plugin you can create SWR hooks based on an operation in the Swagger file.

Installation

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

Options

output

output.path

Output to save the SWR hooks.

INFO

Type: string
Default: 'hooks'

typescript
import { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
output
: {
path
: './hooks',
}, })

output.exportAs

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

INFO

Type: string

typescript
import { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
output
: {
path
: './hooks',
exportAs
: 'hooks',
}, })

output.extName

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

INFO

Type: string

typescript
import { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
output
: {
path
: './hooks',
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 { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
output
: {
path
: './hooks',
exportType
: 'barrel',
}, })

group

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

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

group.exportAs

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

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

INFO

typescript
import { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
group
: {
type
: 'tag',
output
: './hooks/{{tag}}Controller' },
})

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'

typescript
import { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
client
: {
importPath
: '../../client.ts',
}, })

dataReturnType

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

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

TYPE

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

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

typescript
import { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
dataReturnType
: 'data',
})

:::

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 { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
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 { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
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 { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
override
: [
{
type
: 'tag',
pattern
: 'pet',
options
: {
dataReturnType
: 'full',
}, }, ], })

transformers

transformers.name

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

INFO

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

typescript
import { 
pluginSwr
} from '@kubb/swagger-swr'
const
plugin
=
pluginSwr
({
transformers
: {
name
: (
name
) => {
return `${
name
}Hook`
}, }, })

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 { Mutation, Query, QueryOptions } from '@kubb/swagger-swr/components'

export type Templates = {
  mutation: typeof Mutation.templates | false
  query: typeof Query.templates | false
  queryOptions: typeof QueryOptions.templates | false
}

INFO

Type: Templates

tsx
import { 
pluginSwr
} from '@kubb/swagger-swr'
import {
Query
} from '@kubb/swagger-swr/components'
import React from 'react' export const
templates
= {
...
Query
.
templates
,
} as
const
const
plugin
=
pluginSwr
({
templates
: {
query
:
templates
,
}, })

Example

typescript
import { 
defineConfig
} from '@kubb/core'
import {
pluginOas
} from '@kubb/plugin-oas'
import {
pluginSwr
} from '@kubb/swagger-swr'
import {
pluginTs
} from '@kubb/swagger-ts'
export default
defineConfig
({
input
: {
path
: './petStore.yaml',
},
output
: {
path
: './src/gen',
},
plugins
: [
pluginOas
(),
pluginTs
(),
pluginSwr
({
output
: {
path
: './hooks',
},
group
: {
type
: 'tag',
output
: './hooks/{{tag}}Hooks'
},
dataReturnType
: 'full',
parser
: 'zod',
}), ], })

Released under the MIT License.