Continue implementing OpenAPI 3.2.0

Author: SamuelMarks

src/core/types.ts

@@ -26,6 +26,8 @@ export interface LicenseObject {
     url?: string;
     /** An SPDX license identifier for the API. (OAS 3.1+) */
     identifier?: string;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -39,6 +41,8 @@ export interface ContactObject {
     url?: string;
     /** The email address of the contact person/organization. */
     email?: string;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -60,6 +64,8 @@ export interface InfoObject {
     license?: LicenseObject;
     /** The version of the OpenAPI document. */
     version: string;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -71,6 +77,8 @@ export interface ExternalDocumentationObject {
     description?: string;
     /** The URL for the target documentation. */
     url: string;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -90,6 +98,8 @@ export interface TagObject {
     parent?: string;
     /** A machine-readable string to categorize what sort of tag it is. (OAS 3.2+) */
     kind?: string;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -103,6 +113,8 @@ export interface ServerVariableObject {
     default: string;
     /** An optional description for the server variable. */
     description?: string;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -118,6 +130,8 @@ export interface ServerObject {
     name?: string;
     /** A map between a variable name and its value. */
     variables?: { [variable: string]: ServerVariableObject };
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /** Represents the `discriminator` object used for polymorphism in OpenAPI schemas. */
@@ -126,6 +140,8 @@ export interface DiscriminatorObject {
     propertyName: string;
     /** An optional map from a value to a schema reference. */
     mapping?: { [key: string]: string };
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -154,6 +170,8 @@ export interface XmlObject {
      * Values: 'element' | 'attribute' | 'text' | 'cdata' | 'none'.
      */
     nodeType?: 'element' | 'attribute' | 'text' | 'cdata' | 'none' | string;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -173,6 +191,8 @@ export interface LinkObject {
     description?: string;
     /** A server object to be used by the target operation. */
     server?: ServerObject;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -195,6 +215,8 @@ export interface HeaderObject {
     content?: Record<string, { schema?: SwaggerDefinition | { $ref: string } }>;
     example?: any;
     examples?: Record<string, any>;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /** A simplified, normalized representation of an operation parameter. */
@@ -228,6 +250,8 @@ export interface Parameter {
     content?: Record<string, { schema?: SwaggerDefinition | { $ref: string } }>;
     /** Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. */
     deprecated?: boolean;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /** A processed, unified representation of a single API operation (e.g., GET /users/{id}). */
@@ -267,6 +291,8 @@ export interface PathInfo {
     servers?: ServerObject[] | undefined;
     /** A map of possible out-of band callbacks related to the parent operation. (OAS 3+) */
     callbacks?: Record<string, PathItem | { $ref: string }>;
+    /** Specification Extensions (e.g. x-codegen-extra) handled during extraction/normalization */
+    [key: string]: any;
 }
 
 /** A single encoding definition for a multipart property. */
@@ -281,6 +307,8 @@ export interface EncodingProperty {
     explode?: boolean;
     /** allow reserved characters */
     allowReserved?: boolean;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /** Represents the request body of an operation. */
@@ -293,6 +321,8 @@ export interface RequestBody {
         /** Encoding object for multipart/form-data definitions */
         encoding?: Record<string, EncodingProperty>;
     }>;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /** Represents a single response from an API Operation. */
@@ -305,6 +335,8 @@ export interface SwaggerResponse {
     links?: Record<string, LinkObject | { $ref: string }>;
     /** Maps a header name to its definition. */
     headers?: Record<string, HeaderObject | { $ref: string }>;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -384,6 +416,8 @@ export interface SwaggerDefinition {
 
     xml?: XmlObject;
     externalDocs?: ExternalDocumentationObject;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /** Represents a security scheme recognized by the API. */
@@ -394,6 +428,8 @@ export interface SecurityScheme {
     scheme?: 'bearer' | string;
     flows?: Record<string, unknown>;
     openIdConnectUrl?: string;
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 /**
@@ -478,6 +514,8 @@ export interface SwaggerSpec {
     };
     /** Security definitions (Swagger 2.0). */
     securityDefinitions?: { [securityDefinitionName: string]: SecurityScheme };
+    /** Specification Extensions */
+    [key: string]: any;
 }
 
 // ===================================================================================

src/core/utils.ts

@@ -373,6 +373,7 @@ type UnifiedParameter = SwaggerOfficialParameter & {
     allowEmptyValue?: boolean,
     content?: Record<string, { schema?: SwaggerDefinition }>,
     deprecated?: boolean
+    [key: string]: any; // Allow extensions on parameter objects
 };
 
 /**
@@ -536,6 +537,13 @@ export function extractPaths(
                     param.description = p.description;
                 }
 
+                // Propagate extensions like x-codegen-param-name from parameter object to normalized Parameter
+                Object.keys(p).forEach(key => {
+                    if (key.startsWith('x-')) {
+                        (param as any)[key] = (p as any)[key];
+                    }
+                });
+
                 return param;
             });
 
@@ -606,6 +614,14 @@ export function extractPaths(
             if (operation.externalDocs) pathInfo.externalDocs = operation.externalDocs;
             if (effectiveSecurity) pathInfo.security = effectiveSecurity;
 
+            // Propagate custom extensions (x-custom-field) from the operation to PathInfo
+            // This allows generators to access vendor specific metadata on the operation level
+            Object.keys(operation).forEach(key => {
+                if (key.startsWith('x-') && !(key in pathInfo)) {
+                    pathInfo[key] = operation[key];
+                }
+            });
+
             paths.push(pathInfo);
         }
     }

src/core/validator.ts

@@ -18,6 +18,7 @@ export class SpecValidationError extends Error {
  * - Valid version string ('swagger: "2.x"' or 'openapi: "3.x"')
  * - "info" object with "title" and "version"
  * - At least one functional root property ("paths", "components", or "webhooks")
+ * - License Object constraints (mutually exclusive `url` and `identifier`)
  *
  * @param spec The parsed specification object.
  * @throws {SpecValidationError} if the specification is invalid.
@@ -46,7 +47,20 @@ export function validateSpec(spec: SwaggerSpec): void {
         throw new SpecValidationError("Specification info object must contain a required string field: 'version'.");
     }
 
-    // 3. Check Structural Root
+    // 3. Check License Object Constraints (OAS 3.1+)
+    // "The `identifier` field is mutually exclusive of the `url` field."
+    if (spec.info.license) {
+        // OAS 3.2/3.1 Strictness: checking logical existence rather than falsy values to avoid edge cases with empty strings,
+        // though empty strings would be invalid URIs anyway.
+        const hasUrl = spec.info.license.url !== undefined && spec.info.license.url !== null;
+        const hasIdentifier = spec.info.license.identifier !== undefined && spec.info.license.identifier !== null;
+
+        if (hasUrl && hasIdentifier) {
+            throw new SpecValidationError("License object cannot contain both 'url' and 'identifier' fields. They are mutually exclusive.");
+        }
+    }
+
+    // 4. Check Structural Root
     // Per OAS 3.2: "at least one of the components, paths, or webhooks fields MUST be present."
     // For Swagger 2.0: 'paths' is technically required.
 

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

@@ -2,8 +2,8 @@ import { Project } from 'ts-morph';
 
 import { posix as path } from 'node:path';
 
-import { SwaggerParser } from '../../../core/parser.js';
-import { Resource } from '../../../core/types.js';
+import { SwaggerParser } from '@src/core/parser.js';
+import { Resource } from '@src/core/types.js';
 import { discoverAdminResources } from './resource-discovery.js';
 import { FormComponentGenerator } from './form-component.generator.js';
 import { ListComponentGenerator } from './list-component.generator.js';

src/service/emit/admin/custom-validators.generator.ts

@@ -1,6 +1,6 @@
 import { ClassDeclaration, MethodDeclarationStructure, OptionalKind, Project, Scope } from 'ts-morph';
 import { posix as path } from 'node:path';
-import { UTILITY_GENERATOR_HEADER_COMMENT } from '../../../core/constants.js';
+import { UTILITY_GENERATOR_HEADER_COMMENT } from '@src/core/constants.js';
 
 /**
  * Generates the custom-validators.ts file using ts-morph for robust AST manipulation.

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

@@ -1,11 +1,11 @@
 import { ClassDeclaration, Project, Scope, SourceFile } from 'ts-morph';
-import { FormProperty, Resource, SwaggerDefinition } from '../../../core/types.js';
-import { camelCase, getTypeScriptType, pascalCase, singular } from '../../../core/utils.js';
+import { FormProperty, Resource, SwaggerDefinition } from '@src/core/types.js';
+import { camelCase, getTypeScriptType, pascalCase, singular } from '@src/core/utils.js';
 import { commonStandaloneImports } from './common-imports.js';
 import { mapSchemaToFormControl } from './form-control.mapper.js';
 import { generateFormComponentHtml } from './html/form-component-html.builder.js';
 import { generateFormComponentScss } from './html/form-component-scss.builder.js';
-import { SwaggerParser } from '../../../core/parser.js';
+import { SwaggerParser } from '@src/core/parser.js';
 
 /**
  * Orchestrates the generation of a complete Angular standalone form component,

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

@@ -1,7 +1,7 @@
-import { Resource, SwaggerDefinition } from "../../../../core/types.js";
+import { Resource, SwaggerDefinition } from "@src/core/types.js";
 import { HtmlElementBuilder as _ } from '../html-element.builder.js';
 import { buildFormControl } from "./form-controls-html.builder.js";
-import { SwaggerParser } from "../../../../core/parser.js";
+import { SwaggerParser } from "@src/core/parser.js";
 
 /**
  * Generates the complete HTML content for a resource's form component template.

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

@@ -5,8 +5,8 @@
  * with dynamic columns, action buttons, and pagination using the HtmlElementBuilder.
  */
 
-import { Resource } from '../../../../core/types.js';
-import { pascalCase, singular } from '../../../../core/utils.js';
+import { Resource } from '@src/core/types.js';
+import { pascalCase, singular } from '@src/core/utils.js';
 import { HtmlElementBuilder as _ } from '../html-element.builder.js';
 
 /**

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

@@ -1,6 +1,6 @@
 import { ClassDeclaration, Project, Scope } from 'ts-morph';
-import { FormProperty, Resource } from '../../../core/types.js';
-import { camelCase, pascalCase } from '../../../core/utils.js';
+import { FormProperty, Resource } from '@src/core/types.js';
+import { camelCase, pascalCase } from '@src/core/utils.js';
 import { commonStandaloneImports } from './common-imports.js';
 import { generateListComponentHtml } from './html/list-component-html.builder.js';
 import { generateListComponentScss } from './html/list-component-scss.builder.js';

src/service/emit/admin/resource-discovery.ts

@@ -1,15 +1,15 @@
 // src/service/emit/admin/resource-discovery.ts
 
-import { SwaggerParser } from '../../../core/parser.js';
+import { SwaggerParser } from '@src/core/parser.js';
 import {
     DiscriminatorObject,
     FormProperty,
     PathInfo,
     Resource,
     ResourceOperation,
     SwaggerDefinition,
-} from '../../../core/types.js';
-import { camelCase, pascalCase, singular } from '../../../core/utils.js';
+} from '@src/core/types.js';
+import { camelCase, pascalCase, singular } from '@src/core/utils.js';
 
 function getMethodName(op: PathInfo): string {
     const pathToMethodName = (path: string): string =>