@kubb/adapter-oas 5.0.0-beta.3 → 5.0.0-beta.30

package/extension.yaml

@@ -0,0 +1,431 @@
+$schema: https://kubb.dev/schemas/extension.json
+kind: adapter
+id: adapter-oas
+name: OpenAPI
+description: Parse and convert OpenAPI 2.0, 3.0, and 3.1 specifications into Kubb's universal AST. Handles discriminators, date formats, and server URL resolution.
+category: openapi
+type: official
+npmPackage: '@kubb/adapter-oas'
+docsPath: /adapters/adapter-oas
+repo: https://github.com/kubb-labs/kubb
+maintainers:
+  - name: Stijn Van Hulle
+    github: stijnvanhulle
+compatibility:
+  kubb: '>=5.0.0'
+  node: '>=22'
+tags:
+  - openapi
+  - swagger
+  - api-spec
+  - parser
+  - converter
+resources:
+  documentation: https://kubb.dev/adapters/adapter-oas
+  repository: https://github.com/kubb-labs/kubb
+  issues: https://github.com/kubb-labs/kubb/issues
+  changelog: https://github.com/kubb-labs/kubb/blob/main/packages/adapter-oas/CHANGELOG.md
+featured: true
+icon:
+  light: https://kubb.dev/feature/openapi.svg
+intro: |-
+  The OpenAPI adapter is the bridge between your spec and every Kubb plugin. It reads the file at `input.path`, validates it, and converts every schema and operation into Kubb's universal AST that downstream plugins consume.
+
+  Configure it once on `defineConfig`. Its choices (date representation, integer width, server URL) apply to every plugin in the build.
+options:
+  - name: validate
+    type: boolean
+    required: false
+    default: 'true'
+    description: |
+      Validates the OpenAPI spec with `@readme/openapi-parser` before parsing. Set to `false` only when you have a known-invalid spec that you still want to generate from.
+    examples:
+      - name: kubb.config.ts
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |
+              import { defineConfig } from 'kubb'
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              export default defineConfig({
+                input: { path: './petStore.yaml' },
+                output: { path: './src/gen' },
+                adapter: adapterOas({ validate: false }),
+                plugins: [],
+              })
+
+  - name: contentType
+    type: "'application/json' | string"
+    required: false
+    description: |
+      Preferred media type when extracting request and response schemas. Operations with multiple media types fall back to this one.
+
+      Defaults to the first JSON-compatible media type found in the spec (`application/json`, `application/vnd.api+json`, any `*+json`).
+    codeBlock:
+      lang: typescript
+      title: kubb.config.ts
+      twoslash: false
+      code: |-
+        import { defineConfig } from 'kubb'
+        import { adapterOas } from '@kubb/adapter-oas'
+
+        export default defineConfig({
+          input: { path: './petStore.yaml' },
+          output: { path: './src/gen' },
+          adapter: adapterOas({ contentType: 'application/vnd.api+json' }),
+          plugins: [],
+        })
+
+  - name: serverIndex
+    type: number
+    required: false
+    description: |
+      Index into the `servers` array from your OpenAPI spec, used to compute the base URL for plugins that need it (`@kubb/plugin-client`, `@kubb/plugin-msw`, ...).
+
+      Most projects pick `0` for the primary server. Use higher indices to point at staging or localhost when your spec defines multiple environments.
+    tip: |
+      Plugins read `baseURL` from this server unless they override it explicitly.
+    examples:
+      - name: OpenAPI spec
+        files:
+          - lang: yaml
+            twoslash: false
+            code: |-
+              openapi: 3.0.3
+              servers:
+                - url: http://petstore.swagger.io/api
+                - url: http://localhost:3000
+      - name: 'Use the production server'
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              import { defineConfig } from 'kubb'
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              export default defineConfig({
+                input: { path: './petStore.yaml' },
+                output: { path: './src/gen' },
+                adapter: adapterOas({ serverIndex: 0 }),
+                plugins: [],
+              })
+      - name: 'Use the localhost server'
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              import { defineConfig } from 'kubb'
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              export default defineConfig({
+                input: { path: './petStore.yaml' },
+                output: { path: './src/gen' },
+                adapter: adapterOas({ serverIndex: 1 }),
+                plugins: [],
+              })
+
+  - name: serverVariables
+    type: Record<string, string>
+    required: false
+    description: |
+      Values substituted into `{variable}` placeholders in the selected server URL. Only used when `serverIndex` is set. Variables you do not provide use their `default` value from the spec.
+    examples:
+      - name: OpenAPI spec
+        files:
+          - lang: yaml
+            twoslash: false
+            code: |-
+              openapi: 3.0.3
+              servers:
+                - url: https://api.{env}.example.com
+                  variables:
+                    env:
+                      default: dev
+                      enum: [dev, staging, prod]
+      - name: kubb.config.ts
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              import { defineConfig } from 'kubb'
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              export default defineConfig({
+                input: { path: './petStore.yaml' },
+                output: { path: './src/gen' },
+                adapter: adapterOas({
+                  serverIndex: 0,
+                  serverVariables: { env: 'prod' },
+                }),
+                plugins: [],
+              })
+              // baseURL becomes: https://api.prod.example.com
+
+  - name: discriminator
+    type: "'strict' | 'inherit'"
+    required: false
+    default: "'strict'"
+    description: |
+      How `discriminator` fields on `oneOf`/`anyOf` schemas are interpreted.
+
+      - `'strict'` (default) — child schemas stay exactly as written. The discriminator narrows types at the call site but child shapes are not modified.
+      - `'inherit'` — Kubb propagates the discriminator property with the appropriate literal value into each child schema, so each branch's `type` field is precisely typed.
+    details:
+      - title: strict
+        body: 'Child schemas are emitted verbatim. The discriminator property has whatever type the OpenAPI spec gave it.'
+      - title: inherit
+        body: "Each child schema gets the discriminator value as a literal (`type: 'cat'`, `type: 'dog'`). Catches more bugs at compile time."
+    examples:
+      - name: OpenAPI spec
+        files:
+          - lang: yaml
+            twoslash: false
+            code: |-
+              openapi: 3.0.3
+              components:
+                schemas:
+                  Animal:
+                    required: [type]
+                    type: object
+                    oneOf:
+                      - $ref: '#/components/schemas/Cat'
+                      - $ref: '#/components/schemas/Dog'
+                    discriminator:
+                      propertyName: type
+                      mapping:
+                        cat: '#/components/schemas/Cat'
+                        dog: '#/components/schemas/Dog'
+                  Cat:
+                    type: object
+                    properties:
+                      type:
+                        type: string
+                      indoor:
+                        type: boolean
+                  Dog:
+                    type: object
+                    properties:
+                      type:
+                        type: string
+                      name:
+                        type: string
+      - name: "'strict' (default)"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              export type Cat = {
+                type: string
+                indoor?: boolean
+              }
+
+              export type Dog = {
+                type: string
+                name?: string
+              }
+
+              export type Animal = Cat | Dog
+      - name: "'inherit'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              export type Cat = {
+                type: 'cat'
+                indoor?: boolean
+              }
+
+              export type Dog = {
+                type: 'dog'
+                name?: string
+              }
+
+              export type Animal = Cat | Dog
+
+  - name: dateType
+    type: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
+    required: false
+    default: "'string'"
+    description: |
+      How `format: date-time` schemas are represented downstream.
+
+      - `false` — fall through to a plain `string` (no validation).
+      - `'string'` (default) — datetime string (`z.string().datetime()`, ISO 8601).
+      - `'stringOffset'` — datetime string with timezone offset.
+      - `'stringLocal'` — local datetime string (no timezone).
+      - `'date'` — JavaScript `Date` object. Best for client code; requires JSON parsing to revive.
+    examples:
+      - name: 'false'
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              // format: date-time → plain string
+              type CreatedAt = string
+      - name: "'string' (default)"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              // format: date-time → ISO 8601 datetime string
+              type CreatedAt = string
+      - name: "'stringOffset'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              // format: date-time → ISO 8601 datetime with offset
+              type CreatedAt = string
+      - name: "'stringLocal'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              // format: date-time → local ISO 8601 datetime
+              type CreatedAt = string
+      - name: "'date'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              // format: date-time → JavaScript Date
+              type CreatedAt = Date
+
+  - name: integerType
+    type: "'number' | 'bigint'"
+    required: false
+    default: "'number'"
+    description: |
+      How `type: integer` (and `format: int64`) maps to TypeScript.
+
+      - `'number'` (default) — fits most JSON APIs; loses precision above `Number.MAX_SAFE_INTEGER`.
+      - `'bigint'` — exact for 64-bit IDs, but `JSON.stringify`/`JSON.parse` cannot round-trip it. Use only when you also handle bigint serialization explicitly.
+    examples:
+      - name: "'number' (default)"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              type Pet = {
+                id: number
+              }
+      - name: "'bigint'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              type Pet = {
+                id: bigint
+              }
+
+  - name: unknownType
+    type: "'any' | 'unknown' | 'void'"
+    required: false
+    default: "'any'"
+    description: |
+      AST type used when a schema's type cannot be inferred from the spec (`additionalProperties: true`, missing `type`, etc.).
+
+      Pick `'unknown'` to force callers to narrow before using the value. `'any'` is the loosest; `'void'` is rarely useful but matches some legacy APIs.
+    examples:
+      - name: "'any' (default)"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              type Pet = {
+                extra: any
+              }
+      - name: "'unknown'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              type Pet = {
+                extra: unknown
+              }
+      - name: "'void'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              type Pet = {
+                extra: void
+              }
+
+  - name: emptySchemaType
+    type: "'any' | 'unknown' | 'void'"
+    required: false
+    default: unknownType | 'any'
+    description: |
+      AST type used for fully empty schemas (`{}`). Defaults to the value of `unknownType`. Override only when empty schemas should be treated differently from unresolvable ones.
+    tip: |
+      A common pattern: `unknownType: 'unknown'` for safety, `emptySchemaType: 'any'` to keep empty 204 response bodies frictionless to use.
+    examples:
+      - name: "'any' (default)"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              // empty schema {} → any
+              type EmptyModel = any
+      - name: "'unknown'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              // empty schema {} → unknown
+              type EmptyModel = unknown
+
+  - name: enumSuffix
+    type: string
+    required: false
+    default: "'enum'"
+    description: |
+      Suffix appended to derived enum names when Kubb has to invent one (typically for inline enums on object properties).
+
+      Inline enums on a `status` property would be named `statusEnum` with the default. Change this to align with your project's naming convention.
+    examples:
+      - name: "'enum' (default)"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              // Property `status` with inline enum values
+              const statusEnum = { available: 'available', pending: 'pending' } as const
+              type StatusEnum = (typeof statusEnum)[keyof typeof statusEnum]
+      - name: "'type'"
+        files:
+          - lang: typescript
+            twoslash: false
+            code: |-
+              const statusType = { available: 'available', pending: 'pending' } as const
+              type StatusType = (typeof statusType)[keyof typeof statusType]
+examples:
+  - name: kubb.config.ts
+    files:
+      - lang: typescript
+        twoslash: false
+        code: |-
+          import { defineConfig } from 'kubb'
+          import { adapterOas } from '@kubb/adapter-oas'
+          import { pluginTs } from '@kubb/plugin-ts'
+
+          export default defineConfig({
+            input: { path: './petStore.yaml' },
+            output: { path: './src/gen' },
+            adapter: adapterOas({
+              validate: true,
+              serverIndex: 0,
+              serverVariables: { env: 'prod' },
+              discriminator: 'inherit',
+              dateType: 'date',
+              integerType: 'number',
+              unknownType: 'unknown',
+              emptySchemaType: 'unknown',
+              enumSuffix: 'enum',
+            }),
+            plugins: [
+              pluginTs(),
+            ],
+          })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.3",
-  "description": "OpenAPI / Swagger adapter for Kubb converts OAS input into a @kubb/ast RootNode.",
+  "version": "5.0.0-beta.30",
+  "description": "OpenAPI and Swagger adapter for Kubb. Parses and validates OAS 2.0/3.x specifications into a @kubb/ast RootNode for downstream code generation plugins.",
   "keywords": [
     "adapter",
     "codegen",
@@ -21,6 +21,7 @@
   "files": [
     "src",
     "dist",
+    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -42,11 +43,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^2.30.3",
+    "@redocly/openapi-core": "^2.31.2",
     "oas": "^32.1.18",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.3"
+    "@kubb/core": "5.0.0-beta.30"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",
@@ -67,6 +68,7 @@
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
     "start": "tsdown --watch",
+    "bench": "vitest bench",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"
   }

package/src/adapter.bench.ts

@@ -0,0 +1,64 @@
+import path from 'node:path'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { bench, describe } from 'vitest'
+import { adapterOas } from './adapter.ts'
+import { parseDocument } from './factory.ts'
+import { parseOas } from './parser.ts'
+import type { Document } from './types.ts'
+import type { AdapterSource } from '@kubb/core'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const petStorePath = path.resolve(__dirname, '../mocks/petStore.yaml')
+const stripeSpecPath = '/tmp/kubb-stripe-spec3.json'
+const hasStripe = existsSync(stripeSpecPath)
+
+let petStoreDoc: Document | undefined
+
+async function getPetStoreDocument(): Promise<Document> {
+  if (!petStoreDoc) {
+    petStoreDoc = await parseDocument(petStorePath)
+  }
+  return petStoreDoc
+}
+
+describe('parseOas() performance', () => {
+  bench(
+    'petStore spec',
+    async () => {
+      const doc = await getPetStoreDocument()
+      parseOas(doc)
+    },
+    { iterations: 5, warmupIterations: 1 },
+  )
+})
+
+describe.skipIf(!hasStripe)('Stripe spec — batch vs streaming (1,385 schemas)', () => {
+  const stripeSource: AdapterSource = { type: 'path', path: stripeSpecPath }
+
+  bench(
+    'batch — adapter.parse()',
+    async () => {
+      const adapter = adapterOas({ validate: false })
+      await adapter.parse(stripeSource)
+    },
+    { iterations: 3, warmupIterations: 1 },
+  )
+
+  bench(
+    'streaming — adapter.stream() drain',
+    async () => {
+      const adapter = adapterOas({ validate: false })
+      const stream = await adapter.stream!(stripeSource)
+      for await (const _ of stream.schemas) {
+        /* drain */
+      }
+      for await (const _ of stream.operations) {
+        /* drain */
+      }
+    },
+    { iterations: 3, warmupIterations: 1 },
+  )
+})