Continue implementing OpenAPI 3.2.0

Author: SamuelMarks

src/core/parser.ts

@@ -4,15 +4,17 @@
  * parsing, and providing a unified interface to OpenAPI (3.x) and Swagger (2.x) specifications.
  */
 
-import { SwaggerDefinition, SwaggerSpec, GeneratorConfig, SecurityScheme, PathInfo } from './types.js';
+import { GeneratorConfig, PathInfo, SecurityScheme, ServerObject, SwaggerDefinition, SwaggerSpec } from './types.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import yaml from 'js-yaml';
 import { extractPaths, isUrl, pascalCase } from './utils.js';
 
 /** Represents a `$ref` object in a JSON Schema. */
-interface RefObject { $ref: string; }
+interface RefObject {
+    $ref: string;
+}
 
 /**
  * A type guard to safely check if an object is a `$ref` object.
@@ -49,6 +51,8 @@ export class SwaggerParser {
 
     /** A normalized array of all top-level schemas (definitions) found in the entry specification. */
     public readonly schemas: { name: string; definition: SwaggerDefinition; }[];
+    /** A normalized array of all servers defined in the entry specification. */
+    public readonly servers: ServerObject[];
     /** A flattened and processed list of all API operations (paths) from the entry specification. */
     public readonly operations: PathInfo[];
     /** A flattened and processed list of all Webhooks defined in the entry specification. */
@@ -84,6 +88,8 @@ export class SwaggerParser {
             name: pascalCase(name),
             definition
         }));
+
+        this.servers = this.spec.servers || [];
         this.operations = extractPaths(this.spec.paths);
         this.webhooks = extractPaths(this.spec.webhooks);
         this.security = this.getSecuritySchemes();

src/core/types.ts

@@ -8,7 +8,6 @@
  */
 
 import { ModuleKind, ScriptTarget } from "ts-morph";
-import { Path } from 'swagger-schema-official';
 
 // ===================================================================================
 // SECTION: OpenAPI / Swagger Specification Types
@@ -63,6 +62,34 @@ export interface InfoObject {
     version: string;
 }
 
+/**
+ * An object representing a Server Variable for server URL template substitution.
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md#server-variable-object
+ */
+export interface ServerVariableObject {
+    /** An enumeration of string values to be used if the substitution options are from a limited set. */
+    enum?: string[];
+    /** The default value to use for substitution. */
+    default: string;
+    /** An optional description for the server variable. */
+    description?: string;
+}
+
+/**
+ * An object representing a Server.
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md#server-object
+ */
+export interface ServerObject {
+    /** A URL to the target host. */
+    url: string;
+    /** An optional string describing the host designated by the URL. */
+    description?: string;
+    /** An optional unique string to refer to the host designated by the URL. (OAS 3.2) */
+    name?: string;
+    /** A map between a variable name and its value. */
+    variables?: { [variable: string]: ServerVariableObject };
+}
+
 /** Represents the `discriminator` object used for polymorphism in OpenAPI schemas. */
 export interface DiscriminatorObject {
     /** The name of the property in the payload that determines the schema to use. */
@@ -158,14 +185,34 @@ export interface PathInfo {
     responses?: Record<string, SwaggerResponse>;
     /** The generator-derived, safe method name for this operation. */
     methodName?: string;
+    /** Security requirements specific to this operation. keys are definitions, values are scopes. */
+    security?: { [key: string]: string[] }[];
+}
+
+/** A single encoding definition for a multipart property. */
+export interface EncodingProperty {
+    /** The Content-Type for encoding a specific property. */
+    contentType?: string;
+    /** A map of headers that are to be encoded for the property. */
+    headers?: Record<string, any>;
+    /** serialization style */
+    style?: string;
+    /** whether to explode array/objects */
+    explode?: boolean;
+    /** allow reserved characters */
+    allowReserved?: boolean;
 }
 
 /** Represents the request body of an operation. */
 export interface RequestBody {
     /** Determines if the request body is required. */
     required?: boolean;
     /** A map of media types to their corresponding schemas for the request body. */
-    content?: Record<string, { schema?: SwaggerDefinition | { $ref: string } }>;
+    content?: Record<string, {
+        schema?: SwaggerDefinition | { $ref: string };
+        /** Encoding object for multipart/form-data definitions */
+        encoding?: Record<string, EncodingProperty>;
+    }>;
 }
 
 /** Represents a single response from an API Operation. */
@@ -240,24 +287,66 @@ export interface SecurityScheme {
     openIdConnectUrl?: string;
 }
 
+/**
+ * Represents an Operation Object in OpenAPI (v2 or v3).
+ */
+export interface SpecOperation {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+    operationId?: string;
+    consumes?: string[];
+    produces?: string[];
+    parameters?: any[]; // Raw parameters (Swagger 2 or OAS 3)
+    requestBody?: any; // OAS 3
+    responses: Record<string, any>;
+    schemes?: string[];
+    deprecated?: boolean;
+    security?: Record<string, string[]>[];
+    [key: string]: any;
+}
+
+/**
+ * Represents a Path Item Object in OpenAPI (v2 or v3).
+ */
+export interface PathItem {
+    $ref?: string;
+    summary?: string;
+    description?: string;
+    get?: SpecOperation;
+    put?: SpecOperation;
+    post?: SpecOperation;
+    delete?: SpecOperation;
+    options?: SpecOperation;
+    head?: SpecOperation;
+    patch?: SpecOperation;
+    trace?: SpecOperation;
+    query?: SpecOperation; // OAS 3.2 draft
+    parameters?: any[];
+    [key: string]: any;
+}
+
 /** The root object of a parsed OpenAPI/Swagger specification. */
 export interface SwaggerSpec {
     openapi?: string;
     swagger?: string;
     $self?: string;
     info: InfoObject;
-    paths: { [pathName: string]: Path };
+    paths: { [pathName: string]: PathItem };
     /** The incoming webhooks that MAY be received as part of this API. */
-    webhooks?: { [name: string]: Path };
+    webhooks?: { [name: string]: PathItem };
     /** The default value for the $schema keyword within Schema Objects. */
     jsonSchemaDialect?: string;
+    /** An array of Server Objects, which provide connectivity information to a target server. */
+    servers?: ServerObject[];
     /** Schema definitions (Swagger 2.0). */
     definitions?: { [definitionsName: string]: SwaggerDefinition };
     /** Replaces `definitions` in OpenAPI 3.x. */
     components?: {
         schemas?: Record<string, SwaggerDefinition>;
         securitySchemes?: Record<string, SecurityScheme>;
-        pathItems?: Record<string, Path>;
+        pathItems?: Record<string, PathItem>;
     };
     /** Security definitions (Swagger 2.0). */
     securityDefinitions?: { [securityDefinitionName: string]: SecurityScheme };

src/core/utils.ts

@@ -2,19 +2,26 @@
 
 /**
  * @fileoverview
- * This file contains core utility functions used throughout the OpenAPI Angular generator.
+ * This file contains core utility functions used throughout the generator.
  * It includes functions for string manipulation (case conversion), TypeScript type resolution from
  * OpenAPI schemas, OpenAPI spec parsing helpers, and functions for generating unique DI token names.
  * These utilities are pure, dependency-free helpers that form the building blocks of the generation logic.
  */
 
 import { MethodDeclaration } from 'ts-morph';
-import { GeneratorConfig, Parameter, PathInfo, RequestBody, SwaggerDefinition, SwaggerResponse } from './types.js';
+import {
+    GeneratorConfig,
+    Parameter,
+    PathInfo,
+    PathItem,
+    RequestBody,
+    SpecOperation,
+    SwaggerDefinition,
+    SwaggerResponse
+} from './types.js';
 import {
     BodyParameter,
-    Operation,
     Parameter as SwaggerOfficialParameter,
-    Path,
     Response
 } from "swagger-schema-official";
 
@@ -258,11 +265,6 @@ type UnifiedParameter = SwaggerOfficialParameter & {
     content?: Record<string, { schema?: SwaggerDefinition }>
 };
 
-// Helper type that adds OpenAPI 3.x properties to the Swagger 2.0 Operation type
-type OpenAPIOperation = Operation & {
-    requestBody?: RequestBody;
-};
-
 /**
  * Flattens the nested `paths` object from an OpenAPI spec into a linear array of `PathInfo` objects.
  * It merges path-level and operation-level parameters and normalizes Swagger 2.0 `body` parameters
@@ -271,18 +273,21 @@ type OpenAPIOperation = Operation & {
  * @param swaggerPaths The `paths` object from the OpenAPI specification a.k.a `SwaggerSpec['paths']`.
  * @returns An array of processed `PathInfo` objects, or an empty array if `swaggerPaths` is undefined.
  */
-export function extractPaths(swaggerPaths: { [p: string]: Path } | undefined): PathInfo[] {
+export function extractPaths(swaggerPaths: { [p: string]: PathItem } | undefined): PathInfo[] {
     if (!swaggerPaths) {
         return [];
     }
 
     const paths: PathInfo[] = [];
-    const methods = ["get", "post", "put", "patch", "delete", "options", "head"];
+    // Added 'query' to the supported methods list for OAS 3.2 compliance.
+    const methods = ["get", "post", "put", "patch", "delete", "options", "head", "query"];
 
     for (const [path, pathItem] of Object.entries(swaggerPaths)) {
         const pathParameters: UnifiedParameter[] = (pathItem.parameters as UnifiedParameter[]) || [];
         for (const method of methods) {
-            const operation = pathItem[method as keyof Path] as OpenAPIOperation;
+            // Swagger 2.0 Path object is loosely typed here, and doesn't necessarily have 'query' prop.
+            // However, for OAS 3.2, if it exists, we want it.
+            const operation = (pathItem as any)[method] as SpecOperation;
             if (operation) {
                 const paramsMap = new Map<string, UnifiedParameter>();
                 pathParameters.forEach(p => paramsMap.set(`${p.name}:${p.in}`, p));
@@ -391,6 +396,8 @@ export function extractPaths(swaggerPaths: { [p: string]: Path } | undefined): P
                 if (operation.consumes) pathInfo.consumes = operation.consumes;
                 // Add external documentation info from operation
                 if (operation.externalDocs) pathInfo.externalDocs = operation.externalDocs;
+                // Capture security if present
+                if (operation.security) pathInfo.security = operation.security;
 
                 paths.push(pathInfo);
             }

src/service/emit/orchestrator.ts

@@ -19,18 +19,8 @@ import { BaseInterceptorGenerator } from './utility/base-interceptor.generator.j
 import { ProviderGenerator } from './utility/provider.generator.js';
 import { MainIndexGenerator, ServiceIndexGenerator } from './utility/index.generator.js';
 import { ServiceTestGenerator } from "./test/service-test-generator.js";
+import { ServerUrlGenerator } from './utility/server-url.generator.js';
 
-/**
- * Orchestrates the entire code generation process for the Angular client library.
- * It calls specialized generators in a specific order to create models, services,
- * utilities, providers, and optionally an admin UI.
- *
- * @param outputRoot The root directory where all generated files will be written.
- * @param parser An initialized `SwaggerParser` instance containing the API specification.
- * @param config The global generator configuration object.
- * @param project The `ts-morph` project instance to which source files will be added.
- * @returns A promise that resolves when generation is complete.
- */
 export async function emitClientLibrary(outputRoot: string, parser: SwaggerParser, config: GeneratorConfig, project: Project): Promise<void> {
     new TypeGenerator(parser, project, config).generate(outputRoot);
     console.log('✅ Models generated.');
@@ -49,19 +39,18 @@ export async function emitClientLibrary(outputRoot: string, parser: SwaggerParse
         new TokenGenerator(project, config.clientName).generate(outputRoot);
         new HttpParamsBuilderGenerator(project).generate(outputRoot);
         new FileDownloadGenerator(project).generate(outputRoot);
+        new ServerUrlGenerator(parser, project).generate(outputRoot);
+
         if (config.options.dateType === 'Date') {
             new DateTransformerGenerator(project).generate(outputRoot);
         }
 
-        // Check for security schemes to determine if auth-related utilities are needed.
         const securitySchemes = parser.getSecuritySchemes();
-        let tokenNames: string[] = []; // Default to an empty array
+        let tokenNames: string[] = [];
         if (Object.keys(securitySchemes).length > 0) {
             new AuthTokensGenerator(project).generate(outputRoot);
 
             const interceptorGenerator = new AuthInterceptorGenerator(parser, project);
-            // 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);
             tokenNames = interceptorResult?.tokenNames || [];