Kubb

Appearance

@kubb/swagger 🦙 ​

With the Swagger plugin you can create JSON schema's out of a Swagger file. Inside this package you can also use some utils to create your own Swagger plugin. We already provide a react-query plugin but if you want to create a plugin for SWR you can use this package to get the core utils.(check if a schema is v2 or v3, validate the schema, generate a OAS object, ...).

We are using Oas to convert a YAML/JSON to an Oas class(see oasParser) that will contain a lot of extra logic(read the $ref, get all the operations, get all models, ...).

The Swagger plugin also contains some classes and functions that can be used in your own plugin that needs Swagger:

  • For example we have getReference that will return the ref based on the spec.

  • Next to that we also have the class OperationGenerator. This class contains the building blocks of getting the request, response, params, ....
    Just call this.getSchemas and you will retreive an object contains all the info you need to setup a TypeScript type, React-Query hook, ....

Installation ​

shell
bun add @kubb/swagger
bun add @kubb/swagger
shell
pnpm add @kubb/swagger
pnpm add @kubb/swagger
shell
npm install @kubb/swagger
npm install @kubb/swagger
shell
yarn add @kubb/swagger
yarn add @kubb/swagger

Options ​

validate ​

Validate your input(see kubb.config) based on @apidevtools/swagger-parser

INFO

Type: boolean
Default: true

typescript
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ validate: true }),
  ],
})
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

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

output ​

Relative path to save the JSON models.
False will not generate the schema JSON's.

INFO

Type: string | false
Default: 'schemas'

typescript
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: './json' }),
  ],
})
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ output: './json' }),
  ],
})
typescript
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

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

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

serverIndex ​

Which server to use from the array of servers.url[serverIndex]

For example 0 will return http://petstore.swagger.io/api and 1 will return http://localhost:3000

INFO

Type: number
Default: 0

yaml
openapi: 3.0.3
info:
  title: Swagger Example
  description: 
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: http://petstore.swagger.io/api
- url: http://localhost:3000
openapi: 3.0.3
info:
  title: Swagger Example
  description: 
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: http://petstore.swagger.io/api
- url: http://localhost:3000
typescript
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ serverIndex: 0 }), // use of `http://petstore.swagger.io/api`
  ],
})
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ serverIndex: 0 }), // use of `http://petstore.swagger.io/api`
  ],
})
typescript
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ serverIndex: 1 }), // use of `http://localhost:3000`
  ],
})
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ serverIndex: 1 }), // use of `http://localhost:3000`
  ],
})

contentType ​

Override ContentType that wil be used for requests and responses.

type

typescript
export type ContentType = 'application/json' | (string & {})
export type ContentType = 'application/json' | (string & {})

INFO

Type: ContentType

typescript
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ contentType: 'application/json' }),
  ],
})
import { defineConfig } from '@kubb/swagger'
import createSwagger from '@kubb/swagger'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    createSwagger({ contentType: 'application/json' }),
  ],
})

Depended ​

Released under the MIT License.

Copyright © 2022-2024 Stijn Van Hulle