@kubb/adapter-oas 5.0.0-beta.53 → 5.0.0-beta.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.53",
+  "version": "5.0.0-beta.55",
   "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",
@@ -42,16 +42,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@readme/openapi-parser": "^6.1.3",
     "api-ref-bundler": "0.5.1",
-    "js-yaml": "^4.2.0",
-    "oas": "^32.1.18",
-    "oas-normalize": "^16.0.5",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-beta.53",
-    "@kubb/core": "5.0.0-beta.53"
+    "yaml": "^2.9.0",
+    "@kubb/ast": "5.0.0-beta.55",
+    "@kubb/core": "5.0.0-beta.55"
   },
   "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
+    "@types/json-schema": "^7.0.15",
     "@types/swagger2openapi": "^7.0.4",
     "openapi-types": "^12.1.3",
     "@internals/utils": "0.0.0"
@@ -60,6 +59,7 @@
     "node": ">=22"
   },
   "inlinedDependencies": {
+    "@types/json-schema": "7.0.15",
     "openapi-types": "12.1.3"
   },
   "scripts": {

package/src/adapter.ts

@@ -1,12 +1,13 @@
 import { ast, createAdapter } from '@kubb/core'
 import type { AdapterSource } from '@kubb/core'
-import BaseOas from 'oas'
 import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
 import { assertInputExists, parseDocument, parseFromConfig, validateDocument } from './factory.ts'
 import { createSchemaParser } from './parser.ts'
 import { getSchemas } from './resolvers.ts'
 import { createInputStream, preScan, resolveBaseUrl } from './stream.ts'
 import type { AdapterOas, Document } from './types.ts'
+import { collect, narrowSchema } from '@kubb/ast'
+import { extractRefName } from '@kubb/ast/utils'
 
 /**
  * Canonical adapter name for `@kubb/adapter-oas`. Used for driver lookups.
@@ -74,7 +75,6 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
   // resulting document, so distinct configs (distinct documents) stay isolated.
   const documentCache = new WeakMap<AdapterSource, Promise<Document>>()
   const schemasCache = new WeakMap<Document, Promise<ReturnType<typeof getSchemas>['schemas']>>()
-  const baseOasCache = new WeakMap<Document, BaseOas>()
   const schemaParserCache = new WeakMap<Document, ReturnType<typeof createSchemaParser>>()
   const preScanCache = new WeakMap<Document, ReturnType<typeof preScan>>()
 
@@ -105,15 +105,6 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
     return promise
   }
 
-  function ensureBaseOas(document: Document): BaseOas {
-    const cached = baseOasCache.get(document)
-    if (cached) return cached
-
-    const baseOas = new BaseOas(document)
-    baseOasCache.set(document, baseOas)
-    return baseOas
-  }
-
   function ensureSchemaParser(document: Document): ReturnType<typeof createSchemaParser> {
     const cached = schemaParserCache.get(document)
     if (cached) return cached
@@ -128,28 +119,26 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
     schemas: ReturnType<typeof getSchemas>['schemas'],
     parseSchema: ReturnType<typeof ensureSchemaParser>['parseSchema'],
     parseOperation: ReturnType<typeof ensureSchemaParser>['parseOperation'],
-    baseOas: BaseOas,
   ): ReturnType<typeof preScan> {
     const cached = preScanCache.get(document)
     if (cached) return cached
 
-    const result = preScan({ schemas, parseSchema, parseOperation, baseOas, parserOptions, discriminator, dedupe })
+    const result = preScan({ schemas, parseSchema, parseOperation, document, parserOptions, discriminator, dedupe })
     preScanCache.set(document, result)
     return result
   }
 
-  async function createStream(source: AdapterSource): Promise<ast.InputStreamNode> {
+  async function createStream(source: AdapterSource): Promise<ast.InputNode<true>> {
     const document = await ensureDocument(source)
     const schemas = await ensureSchemas(document)
     const { parseSchema, parseOperation } = ensureSchemaParser(document)
-    const baseOas = ensureBaseOas(document)
-    const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(document, schemas, parseSchema, parseOperation, baseOas)
+    const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(document, schemas, parseSchema, parseOperation)
 
     return createInputStream({
       schemas,
       parseSchema,
       parseOperation,
-      baseOas,
+      document,
       parserOptions,
       refAliasMap,
       discriminatorChildMap,
@@ -192,10 +181,13 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
       await validateDocument(document, options)
     },
     getImports(node, resolve) {
-      return ast.collectImports({
-        node,
-        nameMapping,
-        resolve: (schemaName) => {
+      return collect(node, {
+        schema(schemaNode) {
+          const schemaRef = narrowSchema(schemaNode, 'ref')
+          if (!schemaRef?.ref) return null
+
+          const rawName = extractRefName(schemaRef.ref)
+          const schemaName = nameMapping.get(rawName) ?? rawName
           const result = resolve(schemaName)
           if (!result) return null
 

package/src/bundler.ts

@@ -1,6 +1,6 @@
 import { read } from '@internals/utils'
 import { bundle } from 'api-ref-bundler'
-import yaml from 'js-yaml'
+import { parse } from 'yaml'
 import type { Document } from './types.ts'
 
 const urlRegExp = /^https?:\/+/i
@@ -29,7 +29,7 @@ async function resolveSource(sourcePath: string): Promise<object | string> {
     return data
   }
 
-  return yaml.load(data) as object
+  return parse(data) as object
 }
 
 /**

package/src/constants.ts

@@ -31,6 +31,12 @@ export const DEFAULT_PARSER_OPTIONS = {
  */
 export const SCHEMA_REF_PREFIX = '#/components/schemas/' as const
 
+/**
+ * HTTP methods that count as operations on an OpenAPI path item. Other keys
+ * (`parameters`, `summary`, `$ref`, vendor extensions) are skipped when iterating operations.
+ */
+export const SUPPORTED_METHODS: ReadonlySet<string> = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'])
+
 /**
  * OpenAPI version string written into the stub document created during multi-spec merges.
  */

package/src/factory.ts

@@ -1,8 +1,9 @@
 import path from 'node:path'
-import { exists, mergeDeep, URLPath } from '@internals/utils'
+import { exists, mergeDeep, Url } from '@internals/utils'
 import { Diagnostics } from '@kubb/core'
 import type { AdapterSource } from '@kubb/core'
-import OASNormalize from 'oas-normalize'
+import { compileErrors, validate } from '@readme/openapi-parser'
+import { parse } from 'yaml'
 import { bundleDocument } from './bundler.ts'
 import { MERGE_DEFAULT_TITLE, MERGE_DEFAULT_VERSION, MERGE_OPENAPI_VERSION } from './constants.ts'
 import { isOpenApiV2Document } from './guards.ts'
@@ -10,7 +11,6 @@ import type { Document } from './types.ts'
 
 export type ParseOptions = {
   canBundle?: boolean
-  enablePaths?: boolean
 }
 
 export type ValidateDocumentOptions = {
@@ -31,18 +31,16 @@ export type ValidateDocumentOptions = {
  * const document = await parse(rawDocumentObject, { canBundle: false })
  * ```
  */
-export async function parseDocument(pathOrApi: string | Document, { canBundle = true, enablePaths = true }: ParseOptions = {}): Promise<Document> {
+export async function parseDocument(pathOrApi: string | Document, { canBundle = true }: ParseOptions = {}): Promise<Document> {
   if (typeof pathOrApi === 'string' && canBundle) {
     const bundled = await bundleDocument(pathOrApi)
 
-    return parseDocument(bundled, { canBundle: false, enablePaths })
+    return parseDocument(bundled, { canBundle: false })
   }
 
-  const oasNormalize = new OASNormalize(pathOrApi, {
-    enablePaths,
-    colorizeErrors: true,
-  })
-  const document = (await oasNormalize.load()) as Document
+  // A string here is always inline YAML/JSON content: file paths and URLs are read and parsed by
+  // `bundleDocument` first. `yaml.parse` also parses JSON, since JSON is a subset of YAML.
+  const document = (typeof pathOrApi === 'string' ? parse(pathOrApi) : pathOrApi) as Document
 
   if (isOpenApiV2Document(document)) {
     const { default: swagger2openapi } = await import('swagger2openapi')
@@ -59,7 +57,7 @@ export async function parseDocument(pathOrApi: string | Document, { canBundle =
 /**
  * Deep-merges multiple OpenAPI documents into a single `Document`.
  *
- * Each document is parsed independently then recursively merged via `mergeDeep` from `@internals/utils`.
+ * Each document is parsed independently, then deep-merged into one in array order.
  * Throws when the input array is empty.
  *
  * @example
@@ -68,7 +66,7 @@ export async function parseDocument(pathOrApi: string | Document, { canBundle =
  * ```
  */
 export async function mergeDocuments(pathOrApi: Array<string | Document>): Promise<Document> {
-  const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, { enablePaths: false, canBundle: false })))
+  const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, { canBundle: false })))
 
   if (documents.length === 0) {
     throw new Diagnostics.Error({
@@ -123,7 +121,7 @@ export async function parseFromConfig(source: AdapterSource): Promise<Document>
   }
 
   // type === 'path'
-  if (new URLPath(source.path).isURL) {
+  if (Url.canParse(source.path)) {
     return parseDocument(source.path)
   }
 
@@ -138,7 +136,7 @@ export async function parseFromConfig(source: AdapterSource): Promise<Document>
  * its parse error instead.
  */
 export async function assertInputExists(input: string): Promise<void> {
-  if (new URLPath(input).isURL) {
+  if (Url.canParse(input)) {
     return
   }
   if (!(await exists(input))) {
@@ -153,7 +151,7 @@ export async function assertInputExists(input: string): Promise<void> {
 }
 
 /**
- * Validates an OpenAPI document using `oas-normalize` with colorized error output.
+ * Validates an OpenAPI document using `@readme/openapi-parser` with colorized error output.
  *
  * @example
  * ```ts
@@ -162,18 +160,16 @@ export async function assertInputExists(input: string): Promise<void> {
  */
 export async function validateDocument(document: Document, { throwOnError = false }: ValidateDocumentOptions = {}): Promise<void> {
   try {
-    const oasNormalize = new OASNormalize(document, {
-      enablePaths: true,
-      colorizeErrors: true,
-    })
-
-    await oasNormalize.validate({
-      parser: {
-        validate: {
-          errors: { colorize: true },
-        },
+    // `validate` dereferences its input in place, so clone to keep the cached document intact.
+    const result = await validate(structuredClone(document), {
+      validate: {
+        errors: { colorize: true },
       },
     })
+
+    if (!result.valid) {
+      throw new Error(compileErrors(result))
+    }
   } catch (error) {
     if (throwOnError) {
       throw error

package/src/mime.ts

@@ -0,0 +1,22 @@
+/**
+ * MIME type fragments that mark a media type as JSON-like.
+ *
+ * Matches the substrings used by the `oas` library's `matchesMimeType.json`, so a content type is
+ * JSON when it contains any of these. The `+json` entry catches structured-syntax suffixes such as
+ * `application/vnd.api+json`.
+ */
+const jsonMimeFragments = ['application/json', 'application/x-json', 'text/json', 'text/x-json', '+json'] as const
+
+/**
+ * Returns `true` when a media type string is JSON-like.
+ *
+ * @example
+ * ```ts
+ * isJsonMimeType('application/json')         // true
+ * isJsonMimeType('application/vnd.api+json') // true
+ * isJsonMimeType('multipart/form-data')      // false
+ * ```
+ */
+export function isJsonMimeType(mimeType: string): boolean {
+  return jsonMimeFragments.some((fragment) => mimeType.includes(fragment))
+}

package/src/operation.ts

@@ -0,0 +1,194 @@
+import { SUPPORTED_METHODS } from './constants.ts'
+import { isReference } from './guards.ts'
+import { isJsonMimeType } from './mime.ts'
+import { resolveRef } from './refs.ts'
+import type { Document, MediaTypeObject, OperationObject, PathItemObject, ReferenceObject, RequestBodyObject, ResponseObject } from './types.ts'
+
+/**
+ * A single OpenAPI operation: its URL path, HTTP method, and the raw operation object.
+ *
+ * `schema` is a live reference into the document, so any in-place `$ref` resolution the resolvers
+ * perform is visible here too.
+ */
+export type Operation = {
+  path: string
+  method: string
+  schema: OperationObject
+}
+
+/**
+ * The document plus the operation being read. Shared by the request/response accessors so they can
+ * resolve `$ref`s against the document.
+ */
+type OperationContext = {
+  document: Document
+  operation: Operation
+}
+
+/**
+ * Slugifies a path for the `operationId` fallback: non-alphanumerics collapse to single dashes,
+ * with no leading or trailing dash.
+ */
+function slugify(value: string): string {
+  return value
+    .replace(/[^a-zA-Z0-9]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+/**
+ * Returns the operation's `operationId`, falling back to `<method>_<slugified-path>` when absent.
+ */
+export function getOperationId({ path, method, schema }: Operation): string {
+  const { operationId } = schema
+  if (typeof operationId === 'string' && operationId.length > 0) {
+    return operationId
+  }
+  return `${method}_${slugify(path).toLowerCase()}`
+}
+
+/**
+ * Returns the declared response status codes, skipping `x-` extensions and non-object entries.
+ */
+export function getResponseStatusCodes({ schema }: Operation): Array<string> {
+  const responses = schema.responses as Record<string, unknown> | undefined
+  if (!responses || isReference(responses)) {
+    return []
+  }
+  return Object.keys(responses).filter((key) => !key.startsWith('x-') && !!responses[key] && typeof responses[key] === 'object')
+}
+
+/**
+ * Returns the response object for a status code, resolving a `$ref` in place. `false` when absent.
+ */
+export function getResponseByStatusCode({ document, operation, statusCode }: OperationContext & { statusCode: string | number }): ResponseObject | false {
+  const responses = operation.schema.responses as Record<string, ResponseObject | ReferenceObject> | undefined
+  if (!responses || isReference(responses)) {
+    return false
+  }
+  const response = responses[statusCode]
+  if (!response) {
+    return false
+  }
+  if (isReference(response)) {
+    const resolved = resolveRef<ResponseObject>(document, response.$ref)
+    responses[statusCode] = resolved as ResponseObject
+    if (!resolved || isReference(resolved)) {
+      return false
+    }
+    return resolved
+  }
+  return response
+}
+
+/**
+ * Resolves the request body (dereferencing a `$ref` in place) and returns its content map, or
+ * `undefined` when the operation has no request body.
+ */
+function getRequestBodyContent({ document, operation }: OperationContext): Record<string, MediaTypeObject> | undefined {
+  const { schema } = operation
+  let requestBody = schema.requestBody as RequestBodyObject | ReferenceObject | undefined
+  if (!requestBody) {
+    return undefined
+  }
+  if (isReference(requestBody)) {
+    const resolved = resolveRef<RequestBodyObject>(document, requestBody.$ref)
+    ;(schema as { requestBody?: unknown }).requestBody = resolved
+    if (!resolved || isReference(resolved)) {
+      return undefined
+    }
+    requestBody = resolved
+  }
+  return requestBody.content
+}
+
+/**
+ * Returns the request body media type. With `mediaType` set, returns that entry or `false`.
+ * Otherwise picks the first JSON-like media type, then the first declared one, as a
+ * `[mediaType, object]` tuple.
+ */
+export function getRequestContent({
+  document,
+  operation,
+  mediaType,
+}: OperationContext & { mediaType?: string }): MediaTypeObject | false | [string, MediaTypeObject] {
+  const content = getRequestBodyContent({ document, operation })
+  if (!content) {
+    return false
+  }
+  if (mediaType) {
+    return mediaType in content ? content[mediaType]! : false
+  }
+  const mediaTypes = Object.keys(content)
+  const available = mediaTypes.find((mt) => isJsonMimeType(mt)) ?? mediaTypes[0]
+  return available ? [available, content[available]!] : false
+}
+
+/**
+ * Returns the primary request content type. Prefers a JSON-like media type (the last one wins,
+ * matching the previous behavior), then the first declared one, defaulting to `'application/json'`.
+ */
+export function getRequestContentType({ document, operation }: OperationContext): string {
+  const content = getRequestBodyContent({ document, operation })
+  const mediaTypes = content ? Object.keys(content) : []
+
+  let result = mediaTypes[0] ?? 'application/json'
+  for (const mt of mediaTypes) {
+    if (isJsonMimeType(mt)) {
+      result = mt
+    }
+  }
+  return result
+}
+
+/**
+ * Builds an `Operation` for every supported HTTP method on every path, in document order.
+ * `x-` path keys and unresolvable path-item `$ref`s are skipped.
+ *
+ * @example
+ * ```ts
+ * for (const operation of getOperations(document)) {
+ *   parseOperation(options, operation)
+ * }
+ * ```
+ */
+export function getOperations(document: Document): Array<Operation> {
+  const operations: Array<Operation> = []
+  const paths = document.paths
+  if (!paths) {
+    return operations
+  }
+
+  for (const path of Object.keys(paths)) {
+    if (path.startsWith('x-')) {
+      continue
+    }
+
+    let pathItem = paths[path] as PathItemObject | ReferenceObject | undefined
+    if (!pathItem) {
+      continue
+    }
+    if (isReference(pathItem)) {
+      const resolved = resolveRef<PathItemObject>(document, pathItem.$ref)
+      ;(paths as Record<string, unknown>)[path] = resolved
+      if (!resolved || isReference(resolved)) {
+        continue
+      }
+      pathItem = resolved
+    }
+
+    const item = pathItem as Record<string, unknown>
+    for (const method of Object.keys(item)) {
+      if (!SUPPORTED_METHODS.has(method)) {
+        continue
+      }
+      const schema = item[method]
+      if (!schema || typeof schema !== 'object') {
+        continue
+      }
+      operations.push({ path, method, schema: schema as OperationObject })
+    }
+  }
+
+  return operations
+}

package/src/parser.ts

@@ -1,9 +1,9 @@
-import { pascalCase, URLPath } from '@internals/utils'
+import { pascalCase } from '@internals/utils'
 import { childName, enumPropName, extractRefName, findDiscriminator } from '@kubb/ast/utils'
 import { ast } from '@kubb/core'
-import BaseOas from 'oas'
 import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, SCHEMA_REF_PREFIX, typeOptionMap } from './constants.ts'
 import { oasDialect, type OasDialect } from './dialect.ts'
+import { getOperationId, getOperations, getRequestContentType, getResponseByStatusCode, getResponseStatusCodes } from './operation.ts'
 import {
   buildSchemaNode,
   flattenSchema,
@@ -61,11 +61,18 @@ type SchemaContext = {
 }
 
 /**
- * One entry in this adapter's schema-dispatch table, a {@link ast.DispatchRule} specialized
- * to OAS schema context and Kubb `SchemaNode` output. See {@link ast.dispatch} for the contract
- * a future adapter (e.g. AsyncAPI) follows: define a context type and an ordered rules table.
+ * One entry in the ordered schema rule table: a predicate paired with a converter. A rule whose
+ * `match` returns `true` may still `convert` to `null` to defer to the next rule (e.g. a `format`
+ * that is not convertible falls through to plain `type` handling).
  */
-type SchemaRule = ast.DispatchRule<SchemaContext, ast.SchemaNode>
+type SchemaRule = {
+  /** Identifies the rule when reading the table or debugging which branch ran. */
+  name: string
+  /** Returns `true` when this rule is responsible for the given context. */
+  match: (context: SchemaContext) => boolean
+  /** Produces a node for the context, or `null` to fall through to the next rule. */
+  convert: (context: SchemaContext) => ast.SchemaNode | null
+}
 
 /**
  * Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
@@ -772,7 +779,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
   }
 
   /**
-   * Ordered schema-dispatch table. Order is significant: composition keywords (`$ref`, `allOf`,
+   * Ordered schema rule table. Order is significant: composition keywords (`$ref`, `allOf`,
    * `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
    * `type`. The first matching rule that produces a node wins. See {@link SchemaRule} for the
    * match/convert/fall-through contract.
@@ -815,10 +822,10 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
   ]
 
   /**
-   * Central dispatcher that converts an OAS `SchemaObject` into a `SchemaNode`.
+   * Converts an OAS `SchemaObject` into a `SchemaNode`.
    *
-   * Builds the per-schema context, then runs it through the ordered {@link schemaRules} table
-   * via {@link ast.dispatch}. When no rule produces a node, falls back to the configured
+   * Builds the per-schema context, then walks the ordered {@link schemaRules} table and returns
+   * the first converter that produces a node. When none match, falls back to the configured
    * `emptySchemaType`.
    */
   function parseSchema({ schema, name }: { schema: SchemaObject; name?: string | null }, rawOptions?: Partial<ast.ParserOptions>): ast.SchemaNode {
@@ -845,8 +852,11 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       options,
     }
 
-    const node = ast.dispatch(schemaRules, schemaCtx)
-    if (node) return node
+    for (const rule of schemaRules) {
+      if (!rule.match(schemaCtx)) continue
+      const node = rule.convert(schemaCtx)
+      if (node) return node
+    }
 
     const emptyType = typeOptionMap.get(options.emptySchemaType)!
     return ast.createSchema({
@@ -937,7 +947,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
    * Converts an OAS `Operation` into an `OperationNode`.
    */
   function parseOperation(options: ast.ParserOptions, operation: Operation): ast.OperationNode {
-    const operationId = operation.getOperationId()
+    const operationId = getOperationId(operation)
     const operationName = operationId ? pascalCase(operationId) : undefined
     const parameters: Array<ast.ParameterNode> = getParameters(document, operation).map((param) =>
       parseParameter(options, param as unknown as Record<string, unknown>, operationName),
@@ -972,8 +982,8 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
           }
         : undefined
 
-    const responses: Array<ast.ResponseNode> = operation.getResponseStatusCodes().map((statusCode) => {
-      const responseObj = operation.getResponseByStatusCode(statusCode)
+    const responses: Array<ast.ResponseNode> = getResponseStatusCodes(operation).map((statusCode) => {
+      const responseObj = getResponseByStatusCode({ document, operation, statusCode })
 
       // Use `Status<code>` (matching plugin-ts's resolveResponseStatusName convention) so the
       // qualified names for nested enums don't collide with top-level component schemas that
@@ -998,7 +1008,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       // Body-less responses keep a single fallback entry so the response still resolves to a
       // (void/any) schema, matching how `requestBody` only carries schemas inside `content`.
       if (content.length === 0) {
-        content.push({ contentType: operation.contentType || 'application/json', ...parseEntrySchema(ctx.contentType) })
+        content.push({ contentType: getRequestContentType({ document, operation }) || 'application/json', ...parseEntrySchema(ctx.contentType) })
       }
 
       return ast.createResponse({
@@ -1008,17 +1018,24 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       })
     })
 
-    const urlPath = new URLPath(operation.path)
+    const pathItem = document.paths?.[operation.path]
+    const pathItemDoc = pathItem && !dialect.isReference(pathItem) ? (pathItem as { summary?: unknown; description?: unknown }) : undefined
+    const pickDoc = (key: 'summary' | 'description'): string | undefined => {
+      const own = operation.schema[key]
+      if (typeof own === 'string') return own
+      const fallback = pathItemDoc?.[key]
+      return typeof fallback === 'string' ? fallback : undefined
+    }
 
     return ast.createOperation({
       operationId,
       protocol: 'http',
       method: operation.method.toUpperCase() as ast.HttpMethod,
-      path: urlPath.path,
-      tags: operation.getTags().map((tag) => tag.name),
-      summary: operation.getSummary() || undefined,
-      description: operation.getDescription() || undefined,
-      deprecated: operation.isDeprecated() || undefined,
+      path: operation.path,
+      tags: Array.isArray(operation.schema.tags) ? operation.schema.tags.map(String) : [],
+      summary: pickDoc('summary') || undefined,
+      description: pickDoc('description') || undefined,
+      deprecated: operation.schema.deprecated || undefined,
       parameters,
       requestBody,
       responses,
@@ -1084,14 +1101,9 @@ export function parseOas(
 
   const schemas: Array<ast.SchemaNode> = Object.entries(schemaObjects).map(([name, schema]) => _parseSchema({ schema, name }, mergedOptions))
 
-  const baseOas = new BaseOas(document)
-  const paths = baseOas.getPaths()
-
-  const operations: Array<ast.OperationNode> = Object.entries(paths).flatMap(([, methods]) =>
-    Object.entries(methods)
-      .map(([, operation]) => (operation ? _parseOperation(mergedOptions, operation) : null))
-      .filter((op): op is ast.OperationNode => op !== null),
-  )
+  const operations: Array<ast.OperationNode> = getOperations(document)
+    .map((operation) => _parseOperation(mergedOptions, operation))
+    .filter((op): op is ast.OperationNode => op !== null)
 
   const root = ast.createInput({ schemas, operations })