Continue implementing OpenAPI 3.2.0

Author: SamuelMarks

package-lock.json

@@ -47,6 +47,7 @@
   },
   "devDependencies": {
     "@angular/common": "^20.3.12",
+    "@angular/compiler": "^20.3.12",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24",
     "@types/swagger-schema-official": "^2.0.25",
@@ -61,4 +62,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package.json

@@ -29,7 +29,7 @@ export interface Parameter {
     /** The name of the parameter. */
     name: string;
     /** The location of the parameter. */
-    in: "query" | "path" | "header" | "cookie" | "formData";
+    in: "query" | "path" | "header" | "cookie" | "formData" | "querystring";
     /** Determines whether this parameter is mandatory. */
     required?: boolean;
     /** The schema defining the type of the parameter. */
@@ -40,6 +40,14 @@ export interface Parameter {
     format?: string;
     /** A brief description of the parameter. */
     description?: string;
+    /** Describes how the parameter value will be serialized. */
+    style?: string;
+    /** When true, parameter values of type `array` or `object` generate separate parameters. */
+    explode?: boolean;
+    /** Allows sending reserved characters through. */
+    allowReserved?: boolean;
+    /** A map containing the representations for the parameter. For complex serialization scenarios. */
+    content?: Record<string, { schema?: SwaggerDefinition | { $ref: string } }>;
 }
 
 /** A processed, unified representation of a single API operation (e.g., GET /users/{id}). */
@@ -120,7 +128,7 @@ export interface SwaggerDefinition {
     nullable?: boolean;
     required?: string[];
     /** An example of the schema representation. */
-    example?: unknown; // FIX: Added the 'example' property.
+    example?: unknown;
 }
 
 /** Represents a security scheme recognized by the API. */

src/core/types.ts

@@ -221,6 +221,10 @@ type UnifiedParameter = SwaggerOfficialParameter & {
     type?: string,
     format?: string,
     items?: SwaggerDefinition | { $ref: string }
+    // Additions for OAS3 and Swagger2 compatibility
+    collectionFormat?: 'csv' | 'ssv' | 'tsv' | 'pipes' | 'multi' | string,
+    style?: string,
+    explode?: boolean
 };
 
 // Helper type that adds OpenAPI 3.x properties to the Swagger 2.0 Operation type
@@ -267,10 +271,41 @@ export function extractPaths(swaggerPaths: { [p: string]: Path } | undefined): P
 
                     const param: Parameter = {
                         name: p.name,
-                        in: p.in as "query" | "path" | "header" | "cookie",
+                        in: p.in as "query" | "path" | "header" | "cookie" | "querystring",
                         schema: finalSchema as SwaggerDefinition,
                     };
 
+                    // Carry over OAS3 style properties if they exist, but only if they're not undefined to satisfy `exactOptionalPropertyTypes`.
+                    if (p.style !== undefined) {
+                        param.style = p.style;
+                    }
+                    if (p.explode !== undefined) {
+                        param.explode = p.explode;
+                    }
+
+                    // Swagger 2.0 collectionFormat translation
+                    const collectionFormat = p.collectionFormat;
+                    if (collectionFormat) {
+                        switch (collectionFormat) {
+                            case 'csv':
+                                param.style = 'form';
+                                param.explode = false;
+                                break;
+                            case 'ssv':
+                                param.style = 'spaceDelimited';
+                                param.explode = false;
+                                break;
+                            case 'pipes':
+                                param.style = 'pipeDelimited';
+                                param.explode = false;
+                                break;
+                            case 'multi':
+                                param.style = 'form';
+                                param.explode = true;
+                                break;
+                        }
+                    }
+
                     if (p.required !== undefined) {
                         param.required = p.required;
                     }

src/core/utils.ts

@@ -43,8 +43,6 @@ export class AdminGenerator {
                 listGen.generate(resource, adminDir);
             }
 
-            // THE DEFINITIVE FIX: Generate a form if the resource is marked as editable.
-            // This is more robust and correctly handles the failing 'poly' resource case.
             if (resource.isEditable) {
                 const formResult = formGen.generate(resource, adminDir);
                 if (formResult.usesCustomValidators) {

src/service/emit/admin/admin.generator.ts

@@ -377,7 +377,6 @@ export class FormComponentGenerator {
                 docs: [`Getter for the ${singularCamel} FormArray.`]
             });
 
-            // FIX: Move the `docs` from the parameter to the method itself and format with @param.
             const createMethod = classDeclaration.addMethod({
                 name: `create${singularPascal}`,
                 scope: Scope.Private,
@@ -497,7 +496,6 @@ export class FormComponentGenerator {
             body += `if (petType) {\n`;
             body += `  this.form.get(this.discriminatorPropName)?.setValue(petType, { emitEvent: true });\n`;
             for (const subSchemaRef of oneOfProp.schema.oneOf!) {
-                // THE DEFINITIVE FIX: Guard against inline schemas that are not refs.
                 if (!subSchemaRef.$ref) {
                     continue; // Skip primitives like { type: 'string' }
                 }
@@ -532,7 +530,6 @@ export class FormComponentGenerator {
             parameters: [{ name: 'type', type: 'string' }]
         });
 
-        // THE DEFINITIVE FIX: Check if any of the `oneOf` options are objects.
         const oneOfHasObjects = prop.schema.oneOf!.some(s => this.parser.resolve(s)?.properties);
 
         // If none of the `oneOf` options are objects (i.e., they are all primitives like string/number),

src/service/emit/admin/form-component.generator.ts

@@ -7,7 +7,6 @@ export interface FormControlInfo {
 }
 
 export function mapSchemaToFormControl(schema: SwaggerDefinition): FormControlInfo | null {
-    // FIX: Add a null check at the very beginning to prevent crashes.
     if (!schema) {
         return null;
     }

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

@@ -65,8 +65,8 @@ export function generateFormComponentHtml(resource: Resource, parser: SwaggerPar
             const subSchema = option.schema;
 
             // ====================================================================
-            // THE FIX: Create a helper function to recursively merge properties from `allOf`.
-            // This ensures inherited properties (like `name` from `BasePet`) are included.
+            // This helper function recursively merges properties from `allOf`.
+            // ensuring inherited properties (like `name` from `BasePet`) are included.
             // ====================================================================
             const getAllProperties = (schema: SwaggerDefinition): Record<string, SwaggerDefinition> => {
                 let allProperties: Record<string, SwaggerDefinition> = { ...schema.properties };

src/service/emit/admin/html/form-component-html.builder.ts

@@ -63,7 +63,6 @@ export async function emitClientLibrary(outputRoot: string, parser: SwaggerParse
             // generate() returns the names of the tokens used (e.g., 'apiKey', 'bearerToken'),
             // which the ProviderGenerator needs to create the correct configuration interface.
             const interceptorResult = interceptorGenerator.generate(outputRoot);
-            // FIX: Ensure tokenNames is always an array, even if the interceptor isn't generated.
             tokenNames = interceptorResult?.tokenNames || [];
 
             if (Object.values(securitySchemes).some(s => s.type === 'oauth2')) {

src/service/emit/orchestrator.ts

@@ -5,9 +5,9 @@ import {
     ParameterDeclarationStructure,
 } from 'ts-morph';
 import { GeneratorConfig, PathInfo, SwaggerDefinition } from '../../../core/types.js';
-import { SwaggerParser } from '../../../core/parser.js';
 import { camelCase, getTypeScriptType, isDataTypeInterface } from '../../../core/utils.js';
 import { HttpContext, HttpHeaders, HttpParams } from '@angular/common/http';
+import { SwaggerParser } from "@src/core/parser.js";
 
 /** A strongly-typed representation of Angular's HttpRequest options. */
 interface HttpRequestOptions {
@@ -119,15 +119,30 @@ export class ServiceMethodGenerator {
             urlTemplate = urlTemplate.replace(`{${p.name}}`, `\${${camelCase(p.name)}}`);
         });
 
-        const lines = [`const url = \`\${this.basePath}${urlTemplate}\`;`];
+        const lines: string[] = [];
+
+        const cookieParams = operation.parameters?.filter(p => p.in === 'cookie') ?? [];
+        if (cookieParams.length > 0) {
+            lines.push(`// TODO: Cookie parameters are not handled by Angular's HttpClient. You may need to handle them manually.
+console.warn('The following cookie parameters are not automatically handled:', ${JSON.stringify(cookieParams.map(p => p.name))});`);
+        }
+
+        const querystringParams = operation.parameters?.filter(p => p.in === 'querystring') ?? [];
+        if (querystringParams.length > 0) {
+            lines.push(`// TODO: querystring parameters are not handled by Angular's HttpClient. You may need to handle them manually by constructing the URL.
+console.warn('The following querystring parameters are not automatically handled:', ${JSON.stringify(querystringParams.map(p => p.name))});`);
+        }
+        lines.push(`const url = \`\${this.basePath}${urlTemplate}\`;`);
+
         const requestOptions: HttpRequestOptions = {};
 
         const queryParams = operation.parameters?.filter(p => p.in === 'query') ?? [];
         if (queryParams.length > 0) {
             lines.push(`let params = new HttpParams({ fromObject: options?.params ?? {} });`);
             queryParams.forEach(p => {
                 const paramName = camelCase(p.name);
-                lines.push(`if (${paramName} != null) { params = HttpParamsBuilder.addToHttpParams(params, ${paramName}, '${p.name}'); }`);
+                const paramDefJson = JSON.stringify(p);
+                lines.push(`if (${paramName} != null) { params = HttpParamsBuilder.serializeQueryParam(params, ${paramDefJson}, ${paramName}); }`);
             });
             requestOptions.params = 'params' as any; // Use string placeholder
         }
@@ -143,10 +158,10 @@ export class ServiceMethodGenerator {
         }
 
         let optionProperties = `
-  observe: options?.observe,
-  reportProgress: options?.reportProgress,
-  responseType: options?.responseType,
-  withCredentials: options?.withCredentials,
+  observe: options?.observe, 
+  reportProgress: options?.reportProgress, 
+  responseType: options?.responseType, 
+  withCredentials: options?.withCredentials, 
   context: this.createContextWithClientId(options?.context)`;
 
         if (requestOptions.params) {