@kubb/plugin-oas

With the Oas plugin, you can create a JSON schema 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 retrieve an object contains all the info you need to set up a TypeScript type, React-Query hook,....

Installation

bun

bun add @kubb/plugin-oas

pnpm

pnpm add @kubb/plugin-oas

npm

npm install @kubb/plugin-oas

yarn

yarn add @kubb/plugin-oas

Options

validate

Validate your input based on @readme/openapi-parser

INFO

Type: boolean
Default: true

import { pluginOas } from '@kubb/plugin-oas'

const plugin = pluginOas({
  validate: true,
})

output

output.path

Relative path to save the generated files(see generators).

INFO

Type: string
Default: 'schemas'

typescript

import { pluginOas } from '@kubb/plugin-oas'

const plugin = pluginOas({
  output: {
    path: './json',
  },
})

serverIndex

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

For example:

• 0 will return http://petstore.swagger.io/api
• 1 will return http://localhost:3000

INFO

Type: number
Default: 0

OpenAPI

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

serverIndex 0

import { pluginOas } from '@kubb/plugin-oas'

const plugin = pluginOas({ serverIndex: 0 })

serverIndex 1

import { pluginOas } from '@kubb/plugin-oas'

const plugin = pluginOas({ serverIndex: 1 })

contentType

Define which contentType should be used. By default, this is set based on the first used contentType.

TYPE

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

INFO

Type: contentType

import { pluginOas } from '@kubb/plugin-oas'

const plugin = pluginOas({ contentType: 'application/json' })

oasClass

Override some behaviour of the Oas class instance, see @kubb/oas.

INFO

import { pluginOas } from '@kubb/plugin-oas'
import { Oas } from '@kubb/oas'

class oasClass extends Oas {

}

const plugin = pluginOas({
  oasClass
})

generators

Define some generators to create files based on the operation and/or schema. See createGenerator.

All plugin are using generators to create files based on the OperationGenerator and SchemaGenerators.

An empty array will result in no schema's being generated, in v2 of Kubb we used output: false.

INFO

import { pluginOas, createGenerator, PluginOas } from '@kubb/plugin-oas'
import { jsonGenerator } from '@kubb/plugin-oas/generators';

export const customGenerator = createGenerator<PluginOas>({
  name: 'plugin-oas',
  async schema({ schema, name, instance }) {
    return []
  }
})

const plugin = pluginOas({
  generators: [jsonGenerator,  customGenerator]
})

experimentalFilter

INFO

import { pluginOas } from '@kubb/plugin-oas'

const plugin = pluginOas({
  experimentalFilter: {
    methods: ['get'],
  },
})

experimentalSort

INFO

import { pluginOas } from '@kubb/plugin-oas'

const plugin = pluginOas({
  experimentalSort: {
    properties: ['description', 'default', 'type']
  },
})

Example

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'

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

Links

• Oas