Continue implementing OpenAPI 3.2.0

Author: SamuelMarks

src/analysis/form-model.builder.ts

@@ -220,6 +220,14 @@ export class FormModelBuilder {
                 controls: subControls
             });
         }
+
+        // Detect default mapping
+        if (prop.schema.discriminator?.defaultMapping) {
+            const defaultName = pascalCase(prop.schema.discriminator.defaultMapping.split('/').pop() || '');
+            if (defaultName && this.result.polymorphicOptions.some(p => p.modelName === defaultName)) {
+                this.result.defaultPolymorphicOption = defaultName;
+            }
+        }
     }
 
     private getFormControlTypeString(schema: SwaggerDefinition): string {

src/analysis/form-types.ts

@@ -55,4 +55,6 @@ export interface FormAnalysisResult {
     discriminatorPropName?: string;
     discriminatorOptions?: string[]; // List of raw values (['cat', 'dog'])
     polymorphicOptions?: PolymorphicOptionModel[]; // Logic for switching
+    /** The model name of the default option to use if the discriminator value is missing or invalid. */
+    defaultPolymorphicOption?: string;
 }

src/analysis/service-method-analyzer.ts

@@ -25,6 +25,28 @@ export type BodyVariant =
     | { type: 'encoded-form-data'; paramName: string; mappings: string[] } // For legacy formdata loops
     ;
 
+/**
+ * Defines how the response should be deserialized.
+ */
+export type ResponseSerialization =
+    | 'json'
+    | 'text'
+    | 'blob'
+    | 'arraybuffer'
+    | 'sse' // text/event-stream
+    | 'json-seq' // application/json-seq (RFC 7464)
+    | 'json-lines' // application/jsonl, application/x-ndjson
+    | 'xml'; // application/xml
+
+/**
+ * Describes a potential error response from the API.
+ */
+export interface ErrorResponseInfo {
+    code: string;
+    type: string;
+    description?: string;
+}
+
 /**
  * The Intermediate Representation (IR) of a Service Method.
  * This model is framework-agnostic regarding *how* the request is made,
@@ -43,6 +65,13 @@ export interface ServiceMethodModel {
     parameters: OptionalKind<ParameterDeclarationStructure>[];
     responseType: string;
 
+    // Response Handling
+    responseSerialization: ResponseSerialization;
+    responseXmlConfig?: any;
+
+    // Error Handling
+    errorResponses: ErrorResponseInfo[];
+
     // Request Construction Logic
     pathParams: ParamSerialization[];
     queryParams: ParamSerialization[];

src/analysis/service-method-types.ts

@@ -18,4 +18,5 @@ export type ValidationRule =
     | { type: 'multipleOf'; value: number }
     | { type: 'uniqueItems' }
     | { type: 'minItems'; value: number }
-    | { type: 'maxItems'; value: number };
+    | { type: 'maxItems'; value: number }
+    | { type: 'const'; value: any };

src/analysis/validation-types.ts

@@ -17,6 +17,11 @@ export function analyzeValidationRules(schema: SwaggerDefinition): ValidationRul
     // but the resource discovery logic denormalizes this for convenience.
     if ((schema as any).required) rules.push({ type: 'required' });
 
+    // OAS 3.1 const keyword
+    if (schema.const !== undefined) {
+        rules.push({ type: 'const', value: schema.const });
+    }
+
     if (schema.minLength) rules.push({ type: 'minLength', value: schema.minLength });
     if (schema.maxLength) rules.push({ type: 'maxLength', value: schema.maxLength });
     if (schema.pattern) rules.push({ type: 'pattern', value: schema.pattern.replace(/\\\\/g, '\\') });

src/analysis/validation.analyzer.ts

@@ -87,13 +87,20 @@ export class SwaggerParser {
             definition
         }));
 
-        this.servers = this.spec.servers || [];
+        // OAS 3.2 Requirement: If the servers field is not provided, or is an empty array,
+        // the default value would be an array consisting of a single Server Object with a url value of /.
+        if (this.spec.openapi && (!this.spec.servers || this.spec.servers.length === 0)) {
+            this.servers = [{ url: '/' }];
+        } else {
+            this.servers = this.spec.servers || [];
+        }
 
         // We bind resolveReference to this instance so extractPaths can call back into the parser
         const resolveRef = (ref: string) => this.resolveReference(ref);
 
-        this.operations = extractPaths(this.spec.paths, resolveRef);
-        this.webhooks = extractPaths(this.spec.webhooks, resolveRef);
+        // Pass components context to extractPaths for strict security matching
+        this.operations = extractPaths(this.spec.paths, resolveRef, this.spec.components);
+        this.webhooks = extractPaths(this.spec.webhooks, resolveRef, this.spec.components);
 
         this.security = this.getSecuritySchemes();
         this.links = this.getLinks();

src/core/parser.ts

@@ -20,6 +20,9 @@ const isDynamicRefObject = (obj: unknown): obj is DynamicRefObject =>
         $dynamicRef: unknown
     }).$dynamicRef === 'string';
 
+/**
+ * Resolves OpenAPI references ($ref and $dynamicRef) including context-aware resolution for OAS 3.1.
+ */
 export class ReferenceResolver {
     constructor(
         private specCache: Map<string, SwaggerSpec>,
@@ -61,6 +64,7 @@ export class ReferenceResolver {
 
             // $dynamicAnchor
             if ('$dynamicAnchor' in obj && typeof obj.$dynamicAnchor === 'string') {
+                // Store mapping for dynamic anchor in the cache map
                 const anchorUri = `${nextBase}#${obj.$dynamicAnchor}`;
                 if (!cache.has(anchorUri)) {
                     cache.set(anchorUri, obj as SwaggerSpec);
@@ -98,17 +102,24 @@ export class ReferenceResolver {
         return Array.from(refs);
     }
 
-    public resolve<T>(obj: T | { $ref: string } | { $dynamicRef: string } | null | undefined): T | undefined {
+    /**
+     * Resolves an object that might be a reference.
+     * @param obj The object to resolve (or null).
+     * @param resolutionStack The stack of URIs traversed so far (for context-aware $dynamicRef resolution).
+     */
+    public resolve<T>(obj: T | { $ref: string } | {
+        $dynamicRef: string
+    } | null | undefined, resolutionStack: string[] = []): T | undefined {
         if (obj === null || obj === undefined) return undefined;
 
         let resolved: T | undefined;
         let refObj: RefObject | DynamicRefObject | null = null;
 
         if (isRefObject(obj)) {
-            resolved = this.resolveReference<T>(obj.$ref);
+            resolved = this.resolveReference<T>(obj.$ref, this.entryDocumentUri, resolutionStack);
             refObj = obj;
         } else if (isDynamicRefObject(obj)) {
-            resolved = this.resolveReference<T>(obj.$dynamicRef);
+            resolved = this.resolveReference<T>(obj.$dynamicRef, this.entryDocumentUri, resolutionStack);
             refObj = obj;
         } else {
             return obj as T;
@@ -127,9 +138,18 @@ export class ReferenceResolver {
         return resolved;
     }
 
-    public resolveReference<T = SwaggerDefinition>(ref: string, currentDocUri: string = this.entryDocumentUri): T | undefined {
+    /**
+     * Resolves a specific reference string.
+     * @param ref The reference string (URI or fragment).
+     * @param currentDocUri The URI of the document containing the reference.
+     * @param resolutionStack The stack of unique schema URIs encountered during resolution. Used for $dynamicRef lookup.
+     */
+    public resolveReference<T = SwaggerDefinition>(
+        ref: string,
+        currentDocUri: string = this.entryDocumentUri,
+        resolutionStack: string[] = []
+    ): T | undefined {
         if (typeof ref !== 'string') {
-            console.warn(`[Parser] Encountered an unsupported or invalid reference: ${ref}`);
             return undefined;
         }
 
@@ -138,20 +158,34 @@ export class ReferenceResolver {
         const logicalBaseUri = currentDocSpec?.$self ? new URL(currentDocSpec.$self, currentDocUri).href : currentDocUri;
         const targetUri = filePath ? new URL(filePath, logicalBaseUri).href : logicalBaseUri;
 
-        // 1. Direct Cache Lookup ($id/$anchor)
+        // 1. Dynamic Anchor Resolution (OAS 3.1)
+        // Dynamic resolution traverses the stack from the outermost (start of resolution)
+        // to find the first context that defines this anchor.
+        if (jsonPointer && !jsonPointer.includes('/')) {
+            for (const scopeUri of resolutionStack) {
+                const dynamicKey = `${scopeUri}#${jsonPointer}`;
+                if (this.specCache.has(dynamicKey)) {
+                    return this.specCache.get(dynamicKey) as unknown as T;
+                }
+            }
+        }
+
+        // 2. Direct Cache Lookup ($id/$anchor - static)
         const fullUriKey = jsonPointer ? `${targetUri}#${jsonPointer}` : targetUri;
         if (this.specCache.has(fullUriKey)) {
             return this.specCache.get(fullUriKey) as unknown as T;
         }
 
-        // 2. Spec File Cache Lookup
+        // 3. Spec File Cache Lookup
         const targetSpec = this.specCache.get(targetUri);
         if (!targetSpec) {
-            console.warn(`[Parser] Unresolved external file reference: ${targetUri}. File was not pre-loaded.`);
+            if (filePath) {
+                console.warn(`[Parser] Unresolved external file reference: ${targetUri}. File was not pre-loaded.`);
+            }
             return undefined;
         }
 
-        // 3. JSON Pointer Traversal
+        // 4. JSON Pointer Traversal
         let result: any = targetSpec;
         if (jsonPointer) {
             const pointerParts = jsonPointer.split('/').filter(p => p !== '');
@@ -167,11 +201,16 @@ export class ReferenceResolver {
         }
 
         // Handle nested Refs (Recursive resolution)
-        if (isRefObject(result)) {
-            return this.resolveReference(result.$ref, targetUri);
-        }
-        if (isDynamicRefObject(result)) {
-            return this.resolveReference(result.$dynamicRef, targetUri);
+        if (typeof result === 'object' && result !== null) {
+            // Push current scope to stack for dynamic resolution downstream
+            const newStack = [...resolutionStack, fullUriKey];
+
+            if (isRefObject(result)) {
+                return this.resolveReference(result.$ref, targetUri, newStack);
+            }
+            if (isDynamicRefObject(result)) {
+                return this.resolveReference(result.$dynamicRef, targetUri, newStack);
+            }
         }
 
         return result as T;

src/core/parser/reference-resolver.ts

@@ -68,6 +68,7 @@ export interface ServerObject {
 export interface DiscriminatorObject {
     propertyName: string;
     mapping?: { [key: string]: string };
+    defaultMapping?: string;
 
     [key: string]: any;
 }
@@ -153,15 +154,21 @@ export interface RequestBody {
     required?: boolean;
     content?: Record<string, {
         schema?: SwaggerDefinition | { $ref: string };
+        itemSchema?: SwaggerDefinition | { $ref: string };
         encoding?: Record<string, EncodingProperty>;
+        prefixEncoding?: EncodingProperty[];
+        itemEncoding?: EncodingProperty;
     }>;
 
     [key: string]: any;
 }
 
 export interface SwaggerResponse {
     description?: string;
-    content?: Record<string, { schema?: SwaggerDefinition | { $ref: string } }>;
+    content?: Record<string, {
+        schema?: SwaggerDefinition | { $ref: string };
+        itemSchema?: SwaggerDefinition | { $ref: string };
+    }>;
     links?: Record<string, LinkObject | { $ref: string }>;
     headers?: Record<string, HeaderObject | { $ref: string }>;
 

src/core/types/openapi.ts

@@ -34,14 +34,16 @@ type UnifiedParameter = SwaggerOfficialParameter & {
  * - Merging path-level and operation-level parameters.
  * - Resolving references (if a resolver is provided).
  * - Normalizing Swagger 2.0 properties to OpenAPI 3.0 compatible structures.
+ * - Applying OAS 3.2 default serialization rules (style/explode).
  *
  * @param swaggerPaths The raw `paths` object from the specification.
  * @param resolveRef Optional callback to resolve `$ref` pointers within path items.
  * @returns An array of normalized `PathInfo` objects ready for analysis.
  */
 export function extractPaths(
     swaggerPaths: { [p: string]: PathItem } | undefined,
-    resolveRef?: (ref: string) => PathItem | undefined
+    resolveRef?: (ref: string) => PathItem | undefined,
+    components?: { securitySchemes?: Record<string, any> } | undefined
 ): PathInfo[] {
     if (!swaggerPaths) {
         return [];
@@ -50,6 +52,9 @@ export function extractPaths(
     const paths: PathInfo[] = [];
     const methods = ["get", "post", "put", "patch", "delete", "options", "head", "query"];
 
+    // Create a lookup Set for security schemes to enforce precedence rules (OAS 3.2 Security Requirements)
+    const securitySchemeNames = new Set(components?.securitySchemes ? Object.keys(components.securitySchemes) : []);
+
     for (const [path, rawPathItem] of Object.entries(swaggerPaths)) {
         let pathItem = rawPathItem;
 
@@ -154,6 +159,21 @@ export function extractPaths(
                         }
                     }
 
+                    // OAS 3.2 Serialization Defaults
+                    if (!param.style) {
+                        if (param.in === 'query' || param.in === 'cookie') {
+                            param.style = 'form';
+                        } else if (param.in === 'path' || param.in === 'header') {
+                            param.style = 'simple';
+                        }
+                    }
+
+                    if (param.explode === undefined) {
+                        // "When style is form, the default value is true. For all other styles, the default value is false."
+                        // Note: This applies to cookie style='form' as well.
+                        param.explode = (param.style === 'form');
+                    }
+
                     if (p.required !== undefined) param.required = p.required;
                     if (p.description) param.description = p.description;
 
@@ -198,7 +218,14 @@ export function extractPaths(
                 effectiveSecurity = effectiveSecurity.map(req => {
                     const normalizedReq: { [key: string]: string[] } = {};
                     Object.keys(req).forEach(key => {
-                        normalizedReq[normalizeSecurityKey(key)] = req[key];
+                        // OAS 3.2 Precedence: If key matches a component name exactly, assume it is a Component Name.
+                        // Otherwise, treat as URI reference (used for splitting last segment).
+                        // This prevents ambiguity when a Component Name looks like a URI (e.g. "http://auth")
+                        if (securitySchemeNames.has(key)) {
+                            normalizedReq[key] = req[key];
+                        } else {
+                            normalizedReq[normalizeSecurityKey(key)] = req[key];
+                        }
                     });
                     return normalizedReq;
                 });
@@ -273,7 +300,7 @@ function path_to_method_name_suffix(path: string): string {
  */
 export function groupPathsByController(parser: SwaggerParser): Record<string, PathInfo[]> {
     const usedMethodNames = new Set<string>();
-    const allOperations = extractPaths(parser.getSpec().paths);
+    const allOperations = parser.operations; // Use parser.operations which is already extracted
     const groups: Record<string, PathInfo[]> = {};
 
     for (const operation of allOperations) {