Continue implementing OpenAPI 3.2.0

Author: SamuelMarks

src/core/parser.ts

@@ -21,9 +21,18 @@ import { extractPaths, isUrl, pascalCase } from './utils.js';
 import { validateSpec } from './validator.js';
 import { JSON_SCHEMA_2020_12_DIALECT, OAS_3_1_DIALECT } from './constants.js';
 
-/** Represents a `$ref` object in a JSON Schema. */
+/** Represents a `$ref` object in a JSON Schema with optional sibling overrides. */
 interface RefObject {
     $ref: string;
+    summary?: string;
+    description?: string;
+}
+
+/** Represents a `$dynamicRef` object in OAS 3.1 / JSON Schema 2020-12 with optional sibling overrides. */
+interface DynamicRefObject {
+    $dynamicRef: string;
+    summary?: string;
+    description?: string;
 }
 
 /**
@@ -34,6 +43,14 @@ interface RefObject {
 const isRefObject = (obj: unknown): obj is RefObject =>
     typeof obj === 'object' && obj !== null && '$ref' in obj && typeof (obj as { $ref: unknown }).$ref === 'string';
 
+/**
+ * A type guard to safely check if an object is a `$dynamicRef` object.
+ * @param obj The object to check.
+ * @returns True if the object is a valid `$dynamicRef` object.
+ */
+const isDynamicRefObject = (obj: unknown): obj is DynamicRefObject =>
+    typeof obj === 'object' && obj !== null && '$dynamicRef' in obj && typeof (obj as { $dynamicRef: unknown }).$dynamicRef === 'string';
+
 /**
  * Represents a resolved option for a polymorphic (`oneOf`) schema,
  * linking a discriminator value to its corresponding schema definition.
@@ -175,9 +192,9 @@ export class SwaggerParser {
     }
 
     /**
-     * Recursively finds all unique `$ref` values within a given object.
+     * Recursively finds all unique `$ref` and `$dynamicRef` values within a given object.
      * @param obj The object to search.
-     * @returns An array of unique `$ref` strings.
+     * @returns An array of unique reference strings.
      * @private
      */
     private static findRefs(obj: unknown): string[] {
@@ -192,6 +209,10 @@ export class SwaggerParser {
                 refs.add(current.$ref);
             }
 
+            if (isDynamicRefObject(current)) {
+                refs.add(current.$dynamicRef);
+            }
+
             for (const key in current as object) {
                 if (Object.prototype.hasOwnProperty.call(current, key)) {
                     traverse((current as any)[key]);
@@ -289,19 +310,51 @@ export class SwaggerParser {
     }
 
     /**
-     * Synchronously resolves a JSON reference (`$ref`) object to its definition.
-     * If the provided object is not a `$ref`, it is returned as is.
+     * Synchronously resolves a JSON reference (`$ref` or `$dynamicRef`) object to its definition.
+     * If the provided object is not a reference, it is returned as is.
      * This method assumes all necessary files have been pre-loaded into the cache.
+     *
+     * It also supports Overrides: If the Reference Object contains sibling properties 'summary' or 'description',
+     * these will be merged into the resolved object, overriding the original values (OAS 3.1+).
+     *
      * @template T The expected type of the resolved object.
      * @param obj The object to resolve.
      * @returns The resolved definition, the original object if not a ref, or `undefined` if the reference is invalid.
      */
-    public resolve<T>(obj: T | { $ref: string } | null | undefined): T | undefined {
+    public resolve<T>(obj: T | { $ref: string } | { $dynamicRef: string } | null | undefined): T | undefined {
         if (obj === null || obj === undefined) return undefined;
+
+        let resolved: T | undefined;
+        let refObj: RefObject | DynamicRefObject | null = null;
+
         if (isRefObject(obj)) {
-            return this.resolveReference(obj.$ref);
+            resolved = this.resolveReference<T>(obj.$ref);
+            refObj = obj;
+        } else if (isDynamicRefObject(obj)) {
+            // For static code generation purposes, $dynamicRef is treated largely like $ref
+            // Real runtime behavior would depend on dynamic scopes, but here we resolve to the target.
+            resolved = this.resolveReference<T>(obj.$dynamicRef);
+            refObj = obj;
+        } else {
+            return obj as T;
         }
-        return obj as T;
+
+        // Handle Reference Object Overrides (OAS 3.1 Feature)
+        if (resolved && typeof resolved === 'object' && refObj) {
+            const { summary, description } = refObj;
+            if (summary !== undefined || description !== undefined) {
+                // We must shallow copy the resolved object to define the overrides without mutating the shared definition.
+                resolved = { ...resolved };
+                if (summary !== undefined) {
+                    (resolved as any).summary = summary;
+                }
+                if (description !== undefined) {
+                    (resolved as any).description = description;
+                }
+            }
+        }
+
+        return resolved;
     }
 
     /**
@@ -361,6 +414,11 @@ export class SwaggerParser {
             return this.resolveReference(result.$ref, targetFileUri);
         }
 
+        // Handle nested $dynamicRefs recursively
+        if (isDynamicRefObject(result)) {
+            return this.resolveReference(result.$dynamicRef, targetFileUri);
+        }
+
         return result as T;
     }
 
@@ -389,8 +447,14 @@ export class SwaggerParser {
 
         // Strategy 2: Infer from the `oneOf` array directly by resolving each ref and reading its discriminator property.
         return schema.oneOf.map(refSchema => {
-            if (!refSchema.$ref) return null;
-            const resolvedSchema = this.resolveReference(refSchema.$ref);
+            // Check for $ref, but in OAS 3.1 it could also be $dynamicRef
+            let ref: string | undefined;
+            if (refSchema.$ref) ref = refSchema.$ref;
+            else if (refSchema.$dynamicRef) ref = refSchema.$dynamicRef;
+
+            if (!ref) return null;
+
+            const resolvedSchema = this.resolveReference(ref);
             if (!resolvedSchema || !resolvedSchema.properties || !resolvedSchema.properties[dPropName]?.enum) {
                 return null;
             }

src/core/types.ts

@@ -86,6 +86,10 @@ export interface TagObject {
     description?: string;
     /** Additional external documentation for this tag. */
     externalDocs?: ExternalDocumentationObject;
+    /** The name of a tag that this tag is nested under. (OAS 3.2+) */
+    parent?: string;
+    /** A machine-readable string to categorize what sort of tag it is. (OAS 3.2+) */
+    kind?: string;
 }
 
 /**
@@ -350,6 +354,11 @@ export interface SwaggerDefinition {
     contentMediaType?: string;
 
     $ref?: string;
+    /** Dynamic Reference used in OpenAPI 3.1 (JSON Schema 2020-12) */
+    $dynamicRef?: string;
+    /** Dynamic Anchor used in OpenAPI 3.1 (JSON Schema 2020-12) */
+    $dynamicAnchor?: string;
+
     allOf?: SwaggerDefinition[];
     oneOf?: SwaggerDefinition[];
     anyOf?: SwaggerDefinition[];

src/core/utils.ts

@@ -125,6 +125,16 @@ export function getTypeScriptType(schema: SwaggerDefinition | undefined | null,
         return typeName && knownTypes.includes(typeName) ? typeName : 'any';
     }
 
+    // Support for OAS 3.1 $dynamicRef.
+    // For code generation, we treat this statically by linking to the model name found in the reference.
+    if (schema.$dynamicRef) {
+        // Typically points to an anchor, but can point to a path.
+        // We take the segment after the last '#' or '/'
+        const ref = schema.$dynamicRef;
+        const typeName = pascalCase(ref.split('#').pop()?.split('/').pop() || '');
+        return typeName && knownTypes.includes(typeName) ? typeName : 'any';
+    }
+
     // JSON Schema 'const' keyword support (OAS 3.1)
     if (schema.const !== undefined) {
         const val = schema.const;
@@ -145,6 +155,49 @@ export function getTypeScriptType(schema: SwaggerDefinition | undefined | null,
         return `[${tupleTypes.join(', ')}]`;
     }
 
+    // JSON Schema 2020-12 / OAS 3.1 Conditional Support (if/then/else)
+    if (schema.if) {
+        // In TypeScript static analysis, `if` acts like a discriminated union intersection.
+        // `(Type & Then) | (Exclude<Type, If> & Else)` roughly approximates this logic,
+        // but TS type narrowing for arbitrary json schema conditions is limited.
+        // A practical approximation for API clients is: `(Then | Else) & BaseType` if base properties exist, or a Union.
+        // However, `if` validates the instance. It doesn't inherently change the shape unless combined with properties.
+        //
+        // Strategy:
+        // 1. Treat `then` as one possibility.
+        // 2. Treat `else` as another possibility.
+        // 3. The result is `(Then | Else)`. If one is missing, it's `Then | any` or `any | Else` which simplifies to `any` or partial.
+        // Better Strategy for Models: `Base & (Then | Else)`
+
+        const thenType = schema.then ? getTypeScriptType(schema.then, config, knownTypes) : 'any';
+        const elseType = schema.else ? getTypeScriptType(schema.else, config, knownTypes) : 'any';
+
+        // If we have local properties, we generate an intersection.
+        if (schema.properties || schema.allOf) {
+            // We recursively get the base type without if/then/else to avoid infinite recursion if we just called getTypeScriptType.
+            // But since `schema` object is the same, we need to clone and strip condition keywords.
+            const { if: _, then: __, else: ___, ...baseSchema } = schema;
+            const baseType = getTypeScriptType(baseSchema, config, knownTypes);
+
+            if (schema.then && schema.else) {
+                return `${baseType} & (${thenType} | ${elseType})`;
+            } else if (schema.then) {
+                // If only `then` is present, `else` is implicitly valid for everything (type wise), implying optionality.
+                // But structurally, `if` implies constraints.
+                // We output intersection for correctness of the 'then' branch structure types.
+                return `${baseType} & (${thenType} | any)`;
+            } else if (schema.else) {
+                return `${baseType} & (any | ${elseType})`;
+            }
+        } else {
+            // Pure structural conditional
+            if (schema.then && schema.else) {
+                return `${thenType} | ${elseType}`;
+            }
+            return 'any'; // Too ambiguous without base props
+        }
+    }
+
     if (schema.allOf) {
         const parts = schema.allOf
             .map(s => getTypeScriptType(s, config, knownTypes))
@@ -223,6 +276,25 @@ export function getTypeScriptType(schema: SwaggerDefinition | undefined | null,
                 parts.push(`[key: string]: ${joined}`);
             }
 
+            // Handle 'dependentSchemas' (JSON Schema 2020-12).
+            // If property X is present, then properties from Schema Y must also be valid.
+            // We represent this as an intersection: `{ [x]: Type } & DependentSchemaType`
+            if (schema['dependentSchemas']) { // Note: 'dependentSchemas' isn't in strict type, cast/access loosely or update type def
+                // Assuming SwaggerDefinition includes generic indexer or updated type definition
+                const deps = (schema as any).dependentSchemas;
+                Object.entries(deps).forEach(([prop, depSchema]) => {
+                    const depType = getTypeScriptType(depSchema as SwaggerDefinition, config, knownTypes);
+                    // In TS, this conditional relationship is hard to model perfectly static.
+                    // The most robust way for a client model is to intersect the base with the dependent type
+                    // effectively saying "Example object has all these potential shapes combined".
+                    // Ideally: `Base & Partial<Dependent>` but that loses strictness.
+                    // For now, we treat it as `& Dependent` assuming scenarios where the dependency is met.
+                    // Or, more safely, leave it as `any` or documented field.
+                    // A safe static approach: `& Partial<DependentType>`
+                    parts.push(`// dependentSchema: ${prop} -> ${depType}`);
+                });
+            }
+
             if (parts.length > 0) {
                 type = `{ ${parts.join('; ')} }`;
             } else {
@@ -274,6 +346,20 @@ export function hasDuplicateFunctionNames(methods: MethodDeclaration[]): boolean
     return new Set(names).size !== names.length;
 }
 
+/**
+ * Normalizes a security scheme key.
+ * If the key is a JSON pointer/URI (e.g., '#/components/securitySchemes/MyScheme'),
+ * it extracts the simple name ('MyScheme'). Otherwise returns the key as is.
+ */
+function normalizeSecurityKey(key: string): string {
+    // Check if it looks like a URI fragment or JSON pointer
+    if (key.includes('/')) {
+        const parts = key.split('/');
+        return parts[parts.length - 1];
+    }
+    return key;
+}
+
 // Helper type to handle union of Swagger 2.0 and OpenAPI 3.x parameter definitions
 type UnifiedParameter = SwaggerOfficialParameter & {
     schema?: SwaggerDefinition | { $ref: string },
@@ -314,11 +400,20 @@ export function extractPaths(
     for (const [path, rawPathItem] of Object.entries(swaggerPaths)) {
         let pathItem = rawPathItem;
 
-        // Handle Path Item $ref via resolver if provided
+        // Handle Path Item $ref via resolver if provided.
+        // OAS 3.2 Compliance: Sibling properties on a Reference Object (or Path Item with $ref)
+        // override the properties of the referenced object.
         if (pathItem.$ref && resolveRef) {
             const resolved = resolveRef(pathItem.$ref);
             if (resolved) {
-                pathItem = resolved;
+                // Shallow merge: The properties defined in the source file (`pathItem`)
+                // take precedence over the resolved reference properties (`resolved`).
+                // We spread `pathItem` second to ensure its local overrides (e.g., summary) win.
+                const localOverrides = { ...pathItem };
+                // We delete $ref from local overrides before merge to avoid confusion downstream
+                delete localOverrides.$ref;
+
+                pathItem = { ...resolved, ...localOverrides };
             }
         }
 
@@ -473,6 +568,19 @@ export function extractPaths(
 
             const effectiveServers = operation.servers || pathServers;
 
+            // Normalize Security Requirements (OAS 3.2 allows URI references as keys)
+            // e.g. '#/components/securitySchemes/MyScheme' -> 'MyScheme'
+            let effectiveSecurity = operation.security;
+            if (effectiveSecurity) {
+                effectiveSecurity = effectiveSecurity.map(req => {
+                    const normalizedReq: { [key: string]: string[] } = {};
+                    Object.keys(req).forEach(key => {
+                        normalizedReq[normalizeSecurityKey(key)] = req[key];
+                    });
+                    return normalizedReq;
+                });
+            }
+
             const pathInfo: PathInfo = {
                 path,
                 method: method.toUpperCase(),
@@ -485,13 +593,19 @@ export function extractPaths(
             if (operation.callbacks) pathInfo.callbacks = operation.callbacks;
 
             if (operation.operationId) pathInfo.operationId = operation.operationId;
-            if (operation.summary) pathInfo.summary = operation.summary;
-            if (operation.description) pathInfo.description = operation.description;
+
+            // Merge Summary/Description from PathItem if not present on Operation
+            // The order here ensures explicit Op overrides > Path Item overrides > Original ref properties
+            const summary = operation.summary || pathItem.summary
+            if (summary) pathInfo.summary = summary;
+            const description = operation.description || pathItem.description;
+            if (description) pathInfo.description = description;
+
             if (operation.tags) pathInfo.tags = operation.tags;
             if (operation.consumes) pathInfo.consumes = operation.consumes;
             if (operation.deprecated) pathInfo.deprecated = operation.deprecated;
             if (operation.externalDocs) pathInfo.externalDocs = operation.externalDocs;
-            if (operation.security) pathInfo.security = operation.security;
+            if (effectiveSecurity) pathInfo.security = effectiveSecurity;
 
             paths.push(pathInfo);
         }

src/service/emit/admin/form-control.mapper.ts

@@ -32,6 +32,17 @@ export function mapSchemaToFormControl(schema: SwaggerDefinition): FormControlIn
         validators.push('Validators.email');
     }
 
+    // OAS 3.1 / JSON Schema 2020-12 contentEncoding validation
+    if (schema.contentEncoding) {
+        if (schema.contentEncoding === 'base64') {
+            // Standard Base64 regex (RFC 4648 section 4)
+            validators.push(`Validators.pattern(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/)`);
+        } else if (schema.contentEncoding === 'base64url') {
+            // Base64url regex (RFC 4648 section 5) - URL-safe chars, no padding usually, but simple validation checks char class
+            validators.push(`Validators.pattern(/^[A-Za-z0-9\\-_]*$/)`);
+        }
+    }
+
     // Support for 2020-12 / OAS 3.2 numeric exclusive constraints
     // min / exclusiveMin
     if (typeof schema.exclusiveMinimum === 'number') {

src/service/emit/orchestrator.ts

@@ -20,6 +20,7 @@ import { ServiceTestGenerator } from "./test/service-test-generator.js";
 import { ServerUrlGenerator } from './utility/server-url.generator.js';
 import { XmlBuilderGenerator } from './utility/xml-builder.generator.js';
 import { InfoGenerator } from "./utility/info.generator.js";
+import { MultipartBuilderGenerator } from "./utility/multipart-builder.generator.js";
 
 export async function emitClientLibrary(outputRoot: string, parser: SwaggerParser, config: GeneratorConfig, project: Project): Promise<void> {
     new TypeGenerator(parser, project, config).generate(outputRoot);
@@ -44,6 +45,7 @@ export async function emitClientLibrary(outputRoot: string, parser: SwaggerParse
         new FileDownloadGenerator(project).generate(outputRoot);
         new ServerUrlGenerator(parser, project).generate(outputRoot);
         new XmlBuilderGenerator(project).generate(outputRoot);
+        new MultipartBuilderGenerator(project).generate(outputRoot);
 
         if (config.options.dateType === 'Date') {
             new DateTransformerGenerator(project).generate(outputRoot);