@kubb/adapter-oas 5.0.0-alpha.9 → 5.0.0-beta.10

package/extension.yaml

@@ -0,0 +1,344 @@
+$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 with full support for discriminators, date types, and server configuration.
+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 parses and converts your OpenAPI specification into Kubb's internal AST (Abstract Syntax Tree), which all downstream plugins consume.
+
+  The adapter is configured once in `defineConfig` and applies globally to all plugins.
+options:
+  - name: validate
+    type: boolean
+    required: false
+    default: 'true'
+    description: Validate the OpenAPI spec before parsing using `@readme/openapi-parser`.
+  - name: contentType
+    type: "'application/json' | string"
+    required: false
+    description: Preferred content-type used when extracting request/response schemas from the spec. Defaults to the first valid JSON media type found in the spec.
+    codeBlock:
+      lang: typescript
+      title: kubb.config.ts
+      twoslash: false
+      code: |-
+        import { adapterOas } from '@kubb/adapter-oas'
+
+        adapterOas({ contentType: 'application/vnd.api+json' })
+  - name: serverIndex
+    type: number
+    required: false
+    description: Index into the `servers` array from your OpenAPI spec for computing `baseURL`.
+    tip: Defining the server here will make it possible to use that endpoint as `baseURL` in other plugins.
+    examples:
+      - name: OpenAPI
+        files:
+          - lang: yaml
+            code: |-
+              openapi: 3.0.3
+              servers:
+                - url: http://petstore.swagger.io/api
+                - url: http://localhost:3000
+      - name: serverIndex 0
+        files:
+          - lang: typescript
+            code: |-
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              adapterOas({ serverIndex: 0 })
+      - name: serverIndex 1
+        files:
+          - lang: typescript
+            code: |-
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              adapterOas({ serverIndex: 1 })
+  - name: serverVariables
+    type: Record<string, string>
+    required: false
+    description: Override values for `{variable}` placeholders in the selected server URL. Only used when `serverIndex` is set. Variables not provided fall back to their `default` value from the spec.
+    examples:
+      - name: OpenAPI
+        files:
+          - lang: yaml
+            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
+            code: |-
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              adapterOas({
+                serverIndex: 0,
+                serverVariables: { env: 'prod' },
+              })
+              // Results in baseURL: https://api.prod.example.com
+  - name: discriminator
+    type: "'strict' | 'inherit'"
+    required: false
+    default: "'strict'"
+    description: How the discriminator field is interpreted when processing `oneOf`/`anyOf` schemas.
+    details:
+      - title: strict
+        body: Uses `oneOf` schemas as written in the spec. The discriminator is used for type narrowing but child schemas are not modified.
+      - title: inherit
+        body: Propagates the discriminator property with appropriate enum values into each child schema, ensuring type safety and enabling better code generation.
+    examples:
+      - name: OpenAPI
+        files:
+          - lang: yaml
+            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
+        files:
+          - lang: typescript
+            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
+            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 in the generated AST and downstream output."
+    details:
+      - title: 'false'
+        body: Falls through to a plain `string` type.
+      - title: "'string'"
+        body: Emits a datetime string node (e.g. `z.string().datetime()`).
+      - title: "'stringOffset'"
+        body: 'Emits a datetime node with timezone offset (`{ offset: true }`).'
+      - title: "'stringLocal'"
+        body: 'Emits a local datetime node (`{ local: true }`).'
+      - title: "'date'"
+        body: Emits a `date` node (JavaScript `Date` object).
+    examples:
+      - name: 'false'
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → plain string
+              type CreatedAt = string
+      - name: "'string' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → datetime string
+              type CreatedAt = string // validated as ISO 8601 datetime
+      - name: "'stringOffset'"
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → datetime string with offset
+              type CreatedAt = string // validated as ISO 8601 datetime with offset
+      - name: "'stringLocal'"
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → local datetime string
+              type CreatedAt = string // validated as local ISO 8601 datetime
+      - name: "'date'"
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → JavaScript Date
+              type CreatedAt = Date
+  - name: integerType
+    type: "'number' | 'bigint'"
+    required: false
+    default: "'bigint'"
+    description: "Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes."
+    examples:
+      - name: "'number' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                id: number
+              }
+      - name: "'bigint'"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                id: bigint
+              }
+  - name: unknownType
+    type: "'any' | 'unknown' | 'void'"
+    required: false
+    default: "'any'"
+    description: AST type used when no schema type can be inferred from the OpenAPI spec.
+    examples:
+      - name: "'any' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                extra: any
+              }
+      - name: "'unknown'"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                extra: unknown
+              }
+      - name: "'void'"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                extra: void
+              }
+  - name: emptySchemaType
+    type: "'any' | 'unknown' | 'void'"
+    required: false
+    default: unknownType | 'any'
+    description: AST type used for completely empty schemas (`{}`).
+    tip: When not set, `emptySchemaType` falls back to the value of `unknownType`. Set it explicitly only when you want a different type for empty schemas than for unresolvable ones.
+    examples:
+      - name: "'any' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              // empty schema {} → any
+              type EmptyModel = any
+      - name: "'unknown'"
+        files:
+          - lang: typescript
+            code: |-
+              // empty schema {} → unknown
+              type EmptyModel = unknown
+  - name: enumSuffix
+    type: string
+    required: false
+    default: "'enum'"
+    description: Suffix appended to derived enum names when building nested property schema names.
+    examples:
+      - name: "'enum' (default)"
+        files:
+          - lang: typescript
+            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
+            code: |-
+              // enumSuffix: 'type'
+              const statusType = { available: 'available', pending: 'pending' } as const
+              type StatusType = (typeof statusType)[keyof typeof statusType]
+examples:
+  - name: kubb.config.ts
+    files:
+      - lang: typescript
+        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,25 +1,36 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.9",
-  "description": "OpenAPI / Swagger adapter for Kubb — converts OAS input into a @kubb/ast RootNode.",
+  "version": "5.0.0-beta.10",
+  "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": [
-    "openapi",
-    "swagger",
-    "oas",
     "adapter",
-    "kubb",
     "codegen",
+    "kubb",
+    "oas",
+    "openapi",
+    "swagger",
     "typescript"
   ],
+  "license": "MIT",
+  "author": "stijnvanhulle",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kubb-labs/kubb.git",
     "directory": "packages/adapter-oas"
   },
-  "license": "MIT",
-  "author": "stijnvanhulle",
-  "sideEffects": false,
+  "files": [
+    "src",
+    "dist",
+    "extension.yaml",
+    "!/**/**.test.**",
+    "!/**/__tests__/**",
+    "!/**/__snapshots__/**"
+  ],
   "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -27,46 +38,33 @@
     },
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.ts",
-  "files": [
-    "src",
-    "dist",
-    "!/**/**.test.**",
-    "!/**/__tests__/**",
-    "!/**/__snapshots__/**"
-  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "dependencies": {
-    "@kubb/fabric-core": "0.14.0",
-    "@redocly/openapi-core": "^2.24.0",
-    "@stoplight/yaml": "^4.3.0",
-    "fflate": "^0.8.2",
-    "jsonpointer": "^5.0.1",
-    "oas": "^31.1.2",
-    "oas-normalize": "^16.0.2",
-    "openapi-types": "^12.1.3",
-    "remeda": "^2.33.6",
+    "@redocly/openapi-core": "^2.30.4",
+    "oas": "^32.1.18",
+    "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-alpha.9",
-    "@kubb/core": "5.0.0-alpha.9"
+    "@kubb/core": "5.0.0-beta.10"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",
+    "openapi-types": "^12.1.3",
     "@internals/utils": "0.0.0"
   },
   "engines": {
     "node": ">=22"
   },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+  "inlinedDependencies": {
+    "openapi-types": "12.1.3"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
   "scripts": {
     "build": "tsdown",
     "clean": "npx rimraf ./dist",
-    "lint": "bun biome lint .",
-    "lint:fix": "bun biome lint --fix --unsafe .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
     "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",

package/src/adapter.ts

@@ -1,122 +1,130 @@
-import path from 'node:path'
-import { createRoot } from '@kubb/ast'
-import type { AdapterSource } from '@kubb/core'
-import { createAdapter } from '@kubb/core'
-import { resolveServerUrl } from './oas/resolveServerUrl.ts'
-import { parseFromConfig } from './oas/utils.ts'
-import { createOasParser } from './parser.ts'
-import type { OasAdapter } from './types.ts'
-import { getImports } from './utils.ts'
+import { ast, createAdapter } from '@kubb/core'
+import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
+import { applyDiscriminatorInheritance } from './discriminator.ts'
+import { parseDocument, parseFromConfig, validateDocument } from './factory.ts'
+import { parseOas } from './parser.ts'
+import { resolveServerUrl } from './resolvers.ts'
+import type { AdapterOas, Document } from './types.ts'
 
-export const adapterOasName = 'oas' satisfies OasAdapter['name']
+/**
+ * Stable string identifier for the OAS adapter used in Kubb's adapter registry.
+ */
+export const adapterOasName = 'oas' satisfies AdapterOas['name']
 
 /**
- * Creates an OpenAPI / Swagger adapter for Kubb.
+ * Creates the default OpenAPI / Swagger adapter for Kubb.
  *
- * This is the default adapter — you can omit it from your config when using
- * an OpenAPI spec, but supplying it explicitly lets you pass options.
+ * Parses the spec, optionally validates it, resolves the base URL, and converts
+ * everything into an `InputNode` that downstream plugins consume.
  *
  * @example
  * ```ts
- * import { defineConfig } from '@kubb/core'
+ * import { defineConfig } from 'kubb'
  * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
  *
  * export default defineConfig({
- *   adapter: adapterOas({ validate: true, dateType: 'date' }),
- *   input:   { path: './openapi.yaml' },
- *   plugins: [pluginTs(), pluginZod()],
+ *   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
+ *   input: { path: './openapi.yaml' },
+ *   plugins: [pluginTs()],
  * })
  * ```
  */
-export const adapterOas = createAdapter<OasAdapter>((options) => {
+export const adapterOas = createAdapter<AdapterOas>((options) => {
   const {
     validate = true,
-    oasClass,
     contentType,
     serverIndex,
     serverVariables,
     discriminator = 'strict',
-    collisionDetection = false,
-    dateType = 'string',
-    integerType = 'number',
-    unknownType = 'any',
-    emptySchemaType = unknownType,
+    dateType = DEFAULT_PARSER_OPTIONS.dateType,
+    integerType = DEFAULT_PARSER_OPTIONS.integerType,
+    unknownType = DEFAULT_PARSER_OPTIONS.unknownType,
+    enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix,
+    emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType,
   } = options
 
-  // Mutable Map shared between `options` and each `parse()` call.
-  // Populated (and replaced) on every parse so consumers always see the latest state.
-  const nameMapping = new Map<string, string>()
+  // Let-binding so parse() can replace it with a simple reassignment (no clear+loop).
+  let nameMapping = new Map<string, string>()
+  let parsedDocument: Document | null
+  let inputNode: ast.InputNode | null
 
   return {
     name: adapterOasName,
-    options: {
-      validate,
-      oasClass,
-      contentType,
-      serverIndex,
-      serverVariables,
-      discriminator,
-      collisionDetection,
-      dateType,
-      integerType,
-      unknownType,
-      emptySchemaType,
-      nameMapping,
+    get options() {
+      return {
+        validate,
+        contentType,
+        serverIndex,
+        serverVariables,
+        discriminator,
+        dateType,
+        integerType,
+        unknownType,
+        emptySchemaType,
+        enumSuffix,
+        nameMapping,
+      }
+    },
+    get document() {
+      return parsedDocument
+    },
+    get inputNode() {
+      return inputNode
+    },
+    async validate(input, options) {
+      const document = await parseDocument(input)
+      await validateDocument(document, options)
     },
     getImports(node, resolve) {
-      return getImports({ node, nameMapping, resolve })
+      return ast.collectImports({
+        node,
+        nameMapping,
+        resolve: (schemaName) => {
+          const result = resolve(schemaName)
+          if (!result) return
+
+          return ast.createImport({ name: [result.name], path: result.path })
+        },
+      })
     },
     async parse(source) {
-      const fakeConfig = sourceToFakeConfig(source)
-      const oas = await parseFromConfig(fakeConfig, oasClass)
-
-      oas.setOptions({ contentType, discriminator, collisionDetection })
+      const document = await parseFromConfig(source)
 
       if (validate) {
-        try {
-          await oas.validate()
-        } catch (_err) {
-          // Validation failures are non-fatal — mirror plugin-oas behavior
-        }
+        await validateDocument(document)
       }
 
-      const server = serverIndex !== undefined ? oas.api.servers?.at(serverIndex) : undefined
+      const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
       const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : undefined
 
-      const parser = createOasParser(oas, { contentType, collisionDetection })
+      const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
+        contentType,
+        dateType,
+        integerType,
+        unknownType,
+        emptySchemaType,
+        enumSuffix,
+      })
 
-      // Sync the adapter's shared nameMapping with the one computed by the parser.
-      nameMapping.clear()
-      for (const [key, value] of parser.nameMapping) {
-        nameMapping.set(key, value)
-      }
+      const node = discriminator === 'inherit' ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot
 
-      const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType })
+      // This must happen after parseOas() because legacy enum remapping is finalized there.
+      nameMapping = parsedNameMapping
+      // Expose the raw document so consumers (e.g. plugin-redoc) can access it.
+      parsedDocument = document
 
-      return createRoot({
-        ...root,
+      inputNode = ast.createInput({
+        ...node,
         meta: {
-          title: oas.api.info?.title,
-          description: oas.api.info?.description,
-          version: oas.api.info?.version,
+          title: document.info?.title,
+          description: document.info?.description,
+          version: document.info?.version,
           baseURL,
         },
       })
+
+      return inputNode
     },
   }
 })
-
-// TODO: remove once parseFromConfig accepts AdapterSource directly
-function sourceToFakeConfig(source: AdapterSource): Parameters<typeof parseFromConfig>[0] {
-  switch (source.type) {
-    case 'path':
-      return { root: path.dirname(source.path), input: { path: source.path } } as Parameters<typeof parseFromConfig>[0]
-    case 'data':
-      return { root: process.cwd(), input: { data: source.data } } as Parameters<typeof parseFromConfig>[0]
-    case 'paths':
-      return {
-        root: source.paths[0] ? path.dirname(source.paths[0]) : process.cwd(),
-        input: source.paths.map((p) => ({ path: p })),
-      } as Parameters<typeof parseFromConfig>[0]
-  }
-}