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

package/src/factory.ts

@@ -0,0 +1,165 @@
+import path from 'node:path'
+import { mergeDeep, URLPath } from '@internals/utils'
+import type { AdapterSource } from '@kubb/core'
+import { bundle, loadConfig } from '@redocly/openapi-core'
+import OASNormalize from 'oas-normalize'
+import swagger2openapi from 'swagger2openapi'
+import { MERGE_DEFAULT_TITLE, MERGE_DEFAULT_VERSION, MERGE_OPENAPI_VERSION } from './constants.ts'
+import { isOpenApiV2Document } from './guards.ts'
+import type { Document } from './types.ts'
+
+export type ParseOptions = {
+  canBundle?: boolean
+  enablePaths?: boolean
+}
+
+export type ValidateDocumentOptions = {
+  throwOnError?: boolean
+}
+
+/**
+ * Loads and dereferences an OpenAPI document, returning the raw `Document`.
+ *
+ * Accepts a file path string or an already-parsed document object. File paths are bundled via
+ * Redocly to resolve external `$ref`s. Swagger 2.0 documents are automatically up-converted
+ * to OpenAPI 3.0 via `swagger2openapi`.
+ *
+ * @example
+ * ```ts
+ * const document = await parseDocument('./openapi.yaml')
+ * const document = await parse(rawDocumentObject, { canBundle: false })
+ * ```
+ */
+export async function parseDocument(pathOrApi: string | Document, { canBundle = true, enablePaths = true }: ParseOptions = {}): Promise<Document> {
+  if (typeof pathOrApi === 'string' && canBundle) {
+    const config = await loadConfig()
+    const bundleResults = await bundle({
+      ref: pathOrApi,
+      config,
+      base: pathOrApi,
+    })
+
+    return parseDocument(bundleResults.bundle.parsed as string, {
+      canBundle,
+      enablePaths,
+    })
+  }
+
+  const oasNormalize = new OASNormalize(pathOrApi, {
+    enablePaths,
+    colorizeErrors: true,
+  })
+  const document = (await oasNormalize.load()) as Document
+
+  if (isOpenApiV2Document(document)) {
+    const { openapi } = await swagger2openapi.convertObj(document, {
+      anchors: true,
+    })
+
+    return openapi as Document
+  }
+
+  return document
+}
+
+/**
+ * Deep-merges multiple OpenAPI documents into a single `Document`.
+ *
+ * Each document is parsed independently then recursively merged via `mergeDeep` from `@internals/utils`.
+ * Throws when the input array is empty.
+ *
+ * @example
+ * ```ts
+ * const document = await mergeDocuments(['./pets.yaml', './orders.yaml'])
+ * ```
+ */
+export async function mergeDocuments(pathOrApi: Array<string | Document>): Promise<Document> {
+  const documents: Document[] = []
+  for (const p of pathOrApi) {
+    documents.push(await parseDocument(p, { enablePaths: false, canBundle: false }))
+  }
+
+  if (documents.length === 0) {
+    throw new Error('No OAS documents provided for merging.')
+  }
+
+  const seed: Document = {
+    openapi: MERGE_OPENAPI_VERSION,
+    info: { title: MERGE_DEFAULT_TITLE, version: MERGE_DEFAULT_VERSION },
+    paths: {},
+    components: { schemas: {} },
+  } as Document
+
+  const merged = documents.reduce(
+    (acc, current) => mergeDeep(acc as Record<string, unknown>, current as Record<string, unknown>),
+    seed as Record<string, unknown>,
+  )
+
+  return parseDocument(merged as Document)
+}
+
+/**
+ * Creates a `Document` from an `AdapterSource`.
+ *
+ * Handles all three source types:
+ * - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
+ * - `{ type: 'paths' }` — merges multiple file paths into a single document.
+ * - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
+ *
+ * @example
+ * ```ts
+ * const document = await parseFromConfig({ type: 'path', path: './openapi.yaml' })
+ * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
+ * ```
+ */
+export function parseFromConfig(source: AdapterSource): Promise<Document> {
+  if (source.type === 'data') {
+    if (typeof source.data === 'object') {
+      return parseDocument(structuredClone(source.data) as Document)
+    }
+
+    return parseDocument(source.data as string, { canBundle: false })
+  }
+
+  if (source.type === 'paths') {
+    return mergeDocuments(source.paths)
+  }
+
+  // type === 'path'
+  if (new URLPath(source.path).isURL) {
+    return parseDocument(source.path)
+  }
+
+  return parseDocument(path.resolve(path.dirname(source.path), source.path))
+}
+
+/**
+ * Validates an OpenAPI document using `oas-normalize` with colorized error output.
+ *
+ * @example
+ * ```ts
+ * await validateDocument(document)
+ * ```
+ */
+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 },
+        },
+      },
+    })
+  } catch (error) {
+    if (throwOnError) {
+      throw error
+    }
+
+    // Validation failures are non-fatal — mirror plugin-oas behavior
+  }
+}

package/src/guards.ts

@@ -0,0 +1,68 @@
+import { isPlainObject } from '@internals/utils'
+import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
+import type { DiscriminatorObject, SchemaObject } from './types.ts'
+
+/**
+ * Returns `true` when `doc` is a Swagger 2.0 document (no `openapi` key).
+ *
+ * @example
+ * ```ts
+ * if (isOpenApiV2Document(doc)) {
+ *   // doc is OpenAPIV2.Document
+ * }
+ * ```
+ */
+export function isOpenApiV2Document(doc: unknown): doc is OpenAPIV2.Document {
+  return !!doc && isPlainObject(doc) && !('openapi' in doc)
+}
+
+/**
+ * Returns `true` when a schema should be treated as nullable.
+ *
+ * Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
+ * `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
+ *
+ * @example
+ * ```ts
+ * isNullable({ type: 'string', nullable: true }) // true
+ * isNullable({ type: ['string', 'null'] })       // true
+ * isNullable({ type: 'string' })                 // false
+ * ```
+ */
+export function isNullable(schema?: SchemaObject & { 'x-nullable'?: boolean }): boolean {
+  const explicitNullable = schema?.nullable ?? schema?.['x-nullable']
+  if (explicitNullable === true) return true
+
+  const schemaType = schema?.type
+  if (schemaType === 'null') return true
+  if (Array.isArray(schemaType)) return schemaType.includes('null')
+
+  return false
+}
+
+/**
+ * Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
+ *
+ * @example
+ * ```ts
+ * isReference({ $ref: '#/components/schemas/Pet' }) // true
+ * isReference({ type: 'string' })                   // false
+ * ```
+ */
+export function isReference(obj?: unknown): obj is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject {
+  return !!obj && typeof obj === 'object' && '$ref' in obj
+}
+
+/**
+ * Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object.
+ *
+ * @example
+ * ```ts
+ * isDiscriminator({ discriminator: { propertyName: 'type', mapping: {} } }) // true
+ * isDiscriminator({ discriminator: 'type' })                                 // false (Swagger 2 string form)
+ * ```
+ */
+export function isDiscriminator(obj?: unknown): obj is SchemaObject & { discriminator: DiscriminatorObject } {
+  const record = obj as Record<string, unknown>
+  return !!obj && !!record['discriminator'] && typeof record['discriminator'] !== 'string'
+}

package/src/index.ts

@@ -1 +1,18 @@
 export { adapterOas, adapterOasName } from './adapter.ts'
+export type { ParseOptions, ValidateDocumentOptions } from './factory.ts'
+export { mergeDocuments, parseDocument, parseFromConfig, validateDocument } from './factory.ts'
+export type {
+  AdapterOas,
+  AdapterOasOptions,
+  AdapterOasResolvedOptions,
+  ContentType,
+  DiscriminatorObject,
+  Document,
+  HttpMethod,
+  MediaTypeObject,
+  Operation,
+  ReferenceObject,
+  ResponseObject,
+  SchemaObject,
+} from './types.ts'
+export { HttpMethods } from './types.ts'