@kubb/adapter-oas 5.0.0-alpha.43 → 5.0.0-alpha.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.43",
+  "version": "5.0.0-alpha.45",
   "description": "OpenAPI / Swagger adapter for Kubb converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "openapi",
@@ -37,10 +37,10 @@
   ],
   "dependencies": {
     "@redocly/openapi-core": "^2.28.1",
-    "oas": "^31.1.2",
+    "oas": "^32.1.14",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-alpha.43"
+    "@kubb/core": "5.0.0-alpha.45"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/constants.ts

@@ -19,6 +19,18 @@ export const DEFAULT_PARSER_OPTIONS = {
   enumSuffix: 'enum',
 } as const satisfies ast.ParserOptions
 
+/**
+ * JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
+ *
+ * Used when building or parsing `$ref` strings.
+ *
+ * @example
+ * ```ts
+ * `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
+ * ```
+ */
+export const SCHEMA_REF_PREFIX = '#/components/schemas/' as const
+
 /**
  * OpenAPI version string written into the stub document created during multi-spec merges.
  */

package/src/parser.ts

@@ -1,7 +1,7 @@
 import { URLPath } from '@internals/utils'
 import { ast } from '@kubb/core'
 import BaseOas from 'oas'
-import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, typeOptionMap } from './constants.ts'
+import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, SCHEMA_REF_PREFIX, typeOptionMap } from './constants.ts'
 import { isDiscriminator, isNullable, isReference } from './guards.ts'
 import { resolveRef } from './refs.ts'
 import {
@@ -148,7 +148,7 @@ function createSchemaParser(ctx: OasParserContext) {
         if (!deref || !isDiscriminator(deref)) return true
         const parentUnion = deref.oneOf ?? deref.anyOf
         if (!parentUnion) return true
-        const childRef = `#/components/schemas/${name}`
+        const childRef = `${SCHEMA_REF_PREFIX}${name}`
         const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         if (inOneOf || inMapping) {
@@ -697,6 +697,49 @@ function createSchemaParser(ctx: OasParserContext) {
     })
   }
 
+  /**
+   * Reads the inline `requestBody` metadata (description / required / contentType) that OAS exposes
+   * outside the schema itself. Returns an empty object when the request body is missing or a `$ref`.
+   */
+  function getRequestBodyMeta(operation: Operation): { description?: string; required: boolean; contentType?: string } {
+    const body = operation.schema.requestBody
+    if (!body || isReference(body)) return { required: false }
+
+    const inline = body as { description?: string; required?: boolean; content?: Record<string, unknown> }
+    return {
+      description: inline.description,
+      required: inline.required === true,
+      contentType: inline.content ? Object.keys(inline.content)[0] : undefined,
+    }
+  }
+
+  /**
+   * Reads the inline response object (not a `$ref`) and returns its description plus its `content` map.
+   */
+  function getResponseMeta(responseObj: unknown): { description?: string; content?: Record<string, unknown> } {
+    if (typeof responseObj !== 'object' || responseObj === null || Array.isArray(responseObj)) return {}
+
+    const inline = responseObj as { description?: string; content?: Record<string, unknown> }
+    return { description: inline.description, content: inline.content }
+  }
+
+  /**
+   * Collects property names whose schema has a truthy boolean flag (`readOnly` or `writeOnly`).
+   * `$ref` entries are skipped since their flags live on the dereferenced target.
+   */
+  function collectPropertyKeysByFlag(schema: SchemaObject | null, flag: 'readOnly' | 'writeOnly'): string[] | undefined {
+    if (!schema?.properties) return undefined
+
+    const keys: string[] = []
+    for (const key in schema.properties) {
+      const prop = schema.properties[key]
+      if (prop && !isReference(prop) && (prop as Record<string, unknown>)[flag]) {
+        keys.push(key)
+      }
+    }
+    return keys.length ? keys : undefined
+  }
+
   /**
    * Converts an OAS `Operation` into an `OperationNode`.
    */
@@ -707,38 +750,15 @@ function createSchemaParser(ctx: OasParserContext) {
 
     const requestBodySchema = getRequestSchema(document, operation, { contentType: ctx.contentType })
     const requestBodySchemaNode = requestBodySchema ? parseSchema({ schema: requestBodySchema }, options) : undefined
-
-    const requestBodyDescription =
-      operation.schema.requestBody && !isReference(operation.schema.requestBody)
-        ? (operation.schema.requestBody as { description?: string }).description
-        : undefined
-
-    const requestBodyKeysToOmit = requestBodySchema?.properties
-      ? Object.entries(requestBodySchema.properties)
-          .filter(([, prop]) => !isReference(prop) && (prop as { readOnly?: boolean }).readOnly)
-          .map(([key]) => key)
-      : undefined
-
-    const requestBodyRequired =
-      operation.schema.requestBody && !isReference(operation.schema.requestBody)
-        ? (operation.schema.requestBody as { required?: boolean }).required === true
-        : false
-
-    const requestBodyContentType = (() => {
-      if (!operation.schema.requestBody || isReference(operation.schema.requestBody)) {
-        return undefined
-      }
-      const content = (operation.schema.requestBody as { content?: Record<string, unknown> }).content
-      return content ? Object.keys(content)[0] : undefined
-    })()
+    const requestBodyMeta = getRequestBodyMeta(operation)
 
     const requestBody = requestBodySchemaNode
       ? {
-          description: requestBodyDescription,
-          schema: ast.syncOptionality(requestBodySchemaNode, requestBodyRequired),
-          keysToOmit: requestBodyKeysToOmit?.length ? requestBodyKeysToOmit : undefined,
-          required: requestBodyRequired || undefined,
-          contentType: requestBodyContentType,
+          description: requestBodyMeta.description,
+          schema: ast.syncOptionality(requestBodySchemaNode, requestBodyMeta.required),
+          keysToOmit: collectPropertyKeysByFlag(requestBodySchema, 'readOnly'),
+          required: requestBodyMeta.required || undefined,
+          contentType: requestBodyMeta.contentType,
         }
       : undefined
 
@@ -751,27 +771,15 @@ function createSchemaParser(ctx: OasParserContext) {
           ? parseSchema({ schema: responseSchema }, options)
           : ast.createSchema({ type: typeOptionMap.get(options.emptySchemaType)! })
 
-      const description = typeof responseObj === 'object' && responseObj !== null && !Array.isArray(responseObj) ? responseObj.description : undefined
-
-      const rawContent =
-        typeof responseObj === 'object' && responseObj !== null && !Array.isArray(responseObj)
-          ? (responseObj as { content?: Record<string, unknown> }).content
-          : undefined
-
-      const mediaType = rawContent ? getMediaType(Object.keys(rawContent)[0] ?? '') : getMediaType(operation.contentType ?? '')
-
-      const keysToOmit = responseSchema?.properties
-        ? Object.entries(responseSchema.properties)
-            .filter(([, prop]) => !isReference(prop) && (prop as { writeOnly?: boolean }).writeOnly)
-            .map(([key]) => key)
-        : undefined
+      const { description, content } = getResponseMeta(responseObj)
+      const mediaType = content ? getMediaType(Object.keys(content)[0] ?? '') : getMediaType(operation.contentType ?? '')
 
       return ast.createResponse({
         statusCode: statusCode as ast.StatusCode,
         description,
         schema,
         mediaType,
-        keysToOmit: keysToOmit?.length ? keysToOmit : undefined,
+        keysToOmit: collectPropertyKeysByFlag(responseSchema, 'writeOnly'),
       })
     })
 

package/src/resolvers.ts

@@ -3,7 +3,7 @@ import { ast } from '@kubb/core'
 import type { ParameterObject, ServerObject } from 'oas/types'
 import { isRef } from 'oas/types'
 import { matchesMimeType } from 'oas/utils'
-import { formatMap, structuralKeys } from './constants.ts'
+import { formatMap, SCHEMA_REF_PREFIX, structuralKeys } from './constants.ts'
 import { isReference } from './guards.ts'
 import { dereferenceWithRef, resolveRef } from './refs.ts'
 import type { ContentType, Document, MediaTypeObject, Operation, ResponseObject, SchemaObject } from './types.ts'
@@ -128,16 +128,15 @@ function getResponseBody(responseBody: boolean | ResponseObject, contentType?: s
 
   let availableContentType: string | undefined
   const contentTypes = Object.keys(body.content)
-  contentTypes.forEach((mt: string) => {
-    if (!availableContentType && matchesMimeType.json(mt)) {
+  for (const mt of contentTypes) {
+    if (matchesMimeType.json(mt)) {
       availableContentType = mt
+      break
     }
-  })
+  }
 
   if (!availableContentType) {
-    contentTypes.forEach((mt: string) => {
-      if (!availableContentType) availableContentType = mt
-    })
+    availableContentType = contentTypes[0]
   }
 
   if (availableContentType) {
@@ -160,14 +159,13 @@ function getResponseBody(responseBody: boolean | ResponseObject, contentType?: s
  */
 export function getResponseSchema(document: Document, operation: Operation, statusCode: string | number, options: OperationsOptions = {}): SchemaObject {
   if (operation.schema.responses) {
-    Object.keys(operation.schema.responses).forEach((key) => {
-      const schema = operation.schema.responses![key]
-      const $ref = isReference(schema) ? schema.$ref : undefined
-
-      if (schema && $ref) {
-        operation.schema.responses![key] = resolveRef<any>(document, $ref)
+    const responses = operation.schema.responses
+    for (const key in responses) {
+      const schema = responses[key]
+      if (schema && isReference(schema)) {
+        responses[key] = resolveRef<any>(document, schema.$ref)
       }
-    })
+    }
   }
 
   const responseBody = getResponseBody(operation.getResponseByStatusCode(statusCode), options.contentType)
@@ -254,19 +252,30 @@ export type GetSchemasResult = {
  * // returned unchanged — contains a $ref
  * ```
  */
+/**
+ * Returns `true` when `fragment` carries any JSON Schema keyword that makes it
+ * structurally significant on its own (see `structuralKeys`).
+ *
+ * A fragment with a structural keyword can't be safely merged into a parent schema.
+ */
+function hasStructuralKeywords(fragment: SchemaObject): boolean {
+  for (const key in fragment) {
+    if (structuralKeys.has(key as 'properties')) return true
+  }
+  return false
+}
+
 export function flattenSchema(schema: SchemaObject | null): SchemaObject | null {
   if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null
-  if (schema.allOf.some((item) => isRef(item))) return schema
 
-  const isPlainFragment = (item: SchemaObject) => !Object.keys(item).some((key) => structuralKeys.has(key as 'properties'))
-  if (!schema.allOf.every((item) => isPlainFragment(item as SchemaObject))) {
-    return schema
-  }
+  const allOfFragments = schema.allOf as SchemaObject[]
+  if (allOfFragments.some((item) => isRef(item))) return schema
+  if (allOfFragments.some(hasStructuralKeywords)) return schema
 
   const merged: SchemaObject = { ...schema }
   delete merged.allOf
 
-  for (const fragment of schema.allOf as SchemaObject[]) {
+  for (const fragment of allOfFragments) {
     for (const [key, value] of Object.entries(fragment)) {
       if (merged[key as keyof typeof merged] === undefined) {
         merged[key as keyof typeof merged] = value
@@ -311,10 +320,13 @@ function collectRefs(schema: unknown, refs = new Set<string>()): Set<string> {
   }
 
   if (schema && typeof schema === 'object') {
-    for (const [key, value] of Object.entries(schema)) {
+    for (const key in schema) {
+      const value = (schema as Record<string, unknown>)[key]
       if (key === '$ref' && typeof value === 'string') {
-        const match = value.match(/^#\/components\/schemas\/(.+)$/)
-        if (match) refs.add(match[1]!)
+        if (value.startsWith(SCHEMA_REF_PREFIX)) {
+          const name = value.slice(SCHEMA_REF_PREFIX.length)
+          if (name) refs.add(name)
+        }
       } else {
         collectRefs(value, refs)
       }
@@ -424,11 +436,22 @@ export function getSchemas(document: Document, { contentType }: GetSchemasOption
 
   const schemas: Record<string, SchemaObject> = {}
   const nameMapping = new Map<string, string>()
-  const multipleSources = (items: SchemaWithMetadata[]) => new Set(items.map((i) => i.source)).size > 1
 
   for (const [, items] of normalizedNames) {
+    const isSingle = items.length === 1
+    let hasMultipleSources = false
+    if (!isSingle) {
+      const firstSource = items[0]!.source
+      for (let i = 1; i < items.length; i++) {
+        if (items[i]!.source !== firstSource) {
+          hasMultipleSources = true
+          break
+        }
+      }
+    }
+
     items.forEach((item, index) => {
-      const suffix = items.length === 1 ? '' : multipleSources(items) ? getSemanticSuffix(item.source) : index === 0 ? '' : String(index + 1)
+      const suffix = isSingle ? '' : hasMultipleSources ? getSemanticSuffix(item.source) : index === 0 ? '' : String(index + 1)
       const uniqueName = item.originalName + suffix
       schemas[uniqueName] = item.schema
       nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName)