feat(openapi-resource-gen): emit discriminated union types for oneOf/anyOf with discriminator

constantant · claude · constantant · commit bc1b2f49f0e0 · 2026-06-18T13:14:17.000+02:00
When a response schema has discriminator.propertyName + oneOf/anyOf, the generator
now emits XxxDiscriminatorKey (literal union of values), per-variant XxxCat/XxxDog
aliases (using components intersection for mapping-based specs, Extract for enum-based
fallback), and XxxDiscriminated (the proper narrowable union or array thereof).
Imports components from schema.d automatically when mapping-based variants are present.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/tools/openapi-resource-gen/src/generators/api-resource/endpoint-model.ts b/tools/openapi-resource-gen/src/generators/api-resource/endpoint-model.ts
@@ -1,3 +1,17 @@
+export interface DiscriminatorVariant {
+  /** Discriminant literal value, e.g. 'cat'. */
+  key: string;
+  /** Component schema name extracted from discriminator.mapping, e.g. 'Cat'. Absent when only enum-based. */
+  schemaName?: string;
+}
+
+export interface DiscriminatorModel {
+  propertyName: string;
+  variants: DiscriminatorVariant[];
+  /** True when the response schema is an array whose items carry the discriminator. */
+  isArrayResponse: boolean;
+}
+
 /** Non-default serialization style for a query parameter. */
 export type QueryParamSerializer = 'deepObject' | 'csv' | 'pipes' | 'spaces';
 
@@ -52,4 +66,6 @@ export interface EndpointModel {
   deprecated: boolean;
   /** Names of security schemes that apply to this endpoint (resolved from global + operation level). */
   securitySchemeNames: string[];
+  /** Present when the primary response schema carries a discriminator. */
+  discriminator: DiscriminatorModel | null;
 }
diff --git a/tools/openapi-resource-gen/src/generators/api-resource/generator.spec.ts b/tools/openapi-resource-gen/src/generators/api-resource/generator.spec.ts
@@ -893,6 +893,174 @@ describe('api-resource generator', () => {
     });
   });
 
+  describe('discriminated union support', () => {
+    const DISC_SPEC = {
+      paths: {
+        '/events': {
+          get: {
+            operationId: 'listEvents',
+            tags: ['events'],
+            responses: {
+              '200': {
+                content: {
+                  'application/json': {
+                    schema: {
+                      oneOf: [
+                        { type: 'object', properties: { type: { type: 'string' }, x: { type: 'number' } } },
+                        { type: 'object', properties: { type: { type: 'string' }, duration: { type: 'number' } } },
+                      ],
+                      discriminator: {
+                        propertyName: 'type',
+                        mapping: {
+                          click: '#/components/schemas/ClickEvent',
+                          hover: '#/components/schemas/HoverEvent',
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    it('emits DiscriminatorKey union type', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(DISC_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/disc-key/src',
+      });
+      const content = tree.read('libs/disc-key/src/events/list-events.token.ts', 'utf-8')!;
+      expect(content).toContain("export type ListEventsDiscriminatorKey = 'click' | 'hover';");
+    });
+
+    it('emits per-variant narrowed type aliases using component schema intersection', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(DISC_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/disc-variants/src',
+      });
+      const content = tree.read('libs/disc-variants/src/events/list-events.token.ts', 'utf-8')!;
+      expect(content).toContain("components['schemas']['ClickEvent']");
+      expect(content).toContain("components['schemas']['HoverEvent']");
+      // Prettier reformats { "type": "click" } → { type: 'click'; }
+      expect(content).toContain("type: 'click'");
+      expect(content).toContain("type: 'hover'");
+      expect(content).toContain('export type ListEventsClick =');
+      expect(content).toContain('export type ListEventsHover =');
+    });
+
+    it('imports components from schema.d when mapping-based variants are present', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(DISC_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/disc-import/src',
+      });
+      const content = tree.read('libs/disc-import/src/events/list-events.token.ts', 'utf-8')!;
+      expect(content).toContain("import type { paths, components } from '../schema.d'");
+    });
+
+    it('emits XxxDiscriminated union type', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(DISC_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/disc-union/src',
+      });
+      const content = tree.read('libs/disc-union/src/events/list-events.token.ts', 'utf-8')!;
+      expect(content).toContain('export type ListEventsDiscriminated = ListEventsClick | ListEventsHover;');
+    });
+
+    it('wraps XxxDiscriminated in array for array-of-discriminated-items responses', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/events': {
+            get: {
+              operationId: 'listEvents',
+              tags: ['events'],
+              responses: {
+                '200': {
+                  content: {
+                    'application/json': {
+                      schema: {
+                        type: 'array',
+                        items: {
+                          oneOf: [
+                            { type: 'object', properties: { type: { type: 'string' } } },
+                            { type: 'object', properties: { type: { type: 'string' } } },
+                          ],
+                          discriminator: {
+                            propertyName: 'type',
+                            mapping: {
+                              click: '#/components/schemas/ClickEvent',
+                              hover: '#/components/schemas/HoverEvent',
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      } as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/disc-array/src',
+      });
+      const content = tree.read('libs/disc-array/src/events/list-events.token.ts', 'utf-8')!;
+      expect(content).toContain('export type ListEventsDiscriminated = (ListEventsClick | ListEventsHover)[];');
+    });
+
+    it('emits Extract-based variants when only enum values are available (no mapping)', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/events': {
+            get: {
+              operationId: 'listEvents',
+              tags: ['events'],
+              responses: {
+                '200': {
+                  content: {
+                    'application/json': {
+                      schema: {
+                        oneOf: [
+                          { type: 'object', properties: { type: { type: 'string', enum: ['click'] } } },
+                          { type: 'object', properties: { type: { type: 'string', enum: ['hover'] } } },
+                        ],
+                        discriminator: { propertyName: 'type' },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      } as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/disc-enum/src',
+      });
+      const content = tree.read('libs/disc-enum/src/events/list-events.token.ts', 'utf-8')!;
+      expect(content).toContain('Extract<ListEventsResponse,');
+      expect(content).not.toContain("import type { paths, components }");
+    });
+
+    it('does not emit discriminated types when response has no discriminator', async () => {
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/disc-none/src',
+      });
+      const content = tree.read('libs/disc-none/src/pets/list-pets.token.ts', 'utf-8')!;
+      expect(content).not.toContain('DiscriminatorKey');
+      expect(content).not.toContain('Discriminated');
+    });
+  });
+
   describe('descriptive errors', () => {
     it('error message for missing openapi field includes version guidance', () => {
       // Verify the error text is descriptive before we even hit SwaggerParser.
diff --git a/tools/openapi-resource-gen/src/generators/api-resource/parse-spec.ts b/tools/openapi-resource-gen/src/generators/api-resource/parse-spec.ts
@@ -1,6 +1,6 @@
 import SwaggerParser from '@apidevtools/swagger-parser';
 import { OpenAPIV3 } from 'openapi-types';
-import type { EndpointModel, SecurityKind, SecuritySchemeModel, SpecialQueryParam } from './endpoint-model';
+import type { DiscriminatorModel, DiscriminatorVariant, EndpointModel, SecurityKind, SecuritySchemeModel, SpecialQueryParam } from './endpoint-model';
 
 const HTTP_METHODS: ReadonlyArray<OpenAPIV3.HttpMethods> = [
   OpenAPIV3.HttpMethods.GET,
@@ -73,6 +73,38 @@ export function parseSecuritySchemes(api: OpenAPIV3.Document): SecuritySchemeMod
   return result;
 }
 
+function extractDiscriminatorFromSchema(
+  schema: OpenAPIV3.SchemaObject | null | undefined,
+  isArrayResponse: boolean
+): DiscriminatorModel | null {
+  if (!schema?.discriminator?.propertyName) return null;
+
+  const { propertyName, mapping } = schema.discriminator;
+  const variants: DiscriminatorVariant[] = [];
+
+  if (mapping) {
+    for (const [key, ref] of Object.entries(mapping)) {
+      const schemaName = ref.split('/').pop();
+      if (schemaName) variants.push({ key, schemaName });
+    }
+  }
+
+  // Fallback: look for enum values on the discriminator property in each oneOf/anyOf variant.
+  if (variants.length === 0) {
+    const subschemas = [
+      ...((schema.oneOf ?? []) as OpenAPIV3.SchemaObject[]),
+      ...((schema.anyOf ?? []) as OpenAPIV3.SchemaObject[]),
+    ];
+    for (const sub of subschemas) {
+      const discProp = sub.properties?.[propertyName] as OpenAPIV3.SchemaObject | undefined;
+      const enumVal = discProp?.enum?.[0];
+      if (enumVal !== undefined) variants.push({ key: String(enumVal) });
+    }
+  }
+
+  return variants.length > 0 ? { propertyName, variants, isArrayResponse } : null;
+}
+
 export function buildEndpoints(
   api: OpenAPIV3.Document,
   allowedTags: string[] | null,
@@ -187,6 +219,20 @@ export function buildEndpoints(
 
       const deprecated = operation.deprecated === true;
 
+      // Detect discriminated union on the primary response schema.
+      let discriminator: DiscriminatorModel | null = null;
+      if (responseStatuses.length > 0) {
+        const primaryResponseObj = operation.responses?.[responseStatuses[0]] as OpenAPIV3.ResponseObject | undefined;
+        const primarySchema = primaryResponseObj?.content?.['application/json']?.schema as OpenAPIV3.SchemaObject | undefined;
+        if (primarySchema) {
+          discriminator =
+            extractDiscriminatorFromSchema(primarySchema, false) ??
+            (primarySchema.type === 'array'
+              ? extractDiscriminatorFromSchema(primarySchema.items as OpenAPIV3.SchemaObject, true)
+              : null);
+        }
+      }
+
       endpoints.push({
         tag: toKebabCase(tag),
         operationId: rawId,
@@ -207,6 +253,7 @@ export function buildEndpoints(
         deprecated,
         securitySchemeNames,
         errorStatuses,
+        discriminator,
       });
     }
   }
diff --git a/tools/openapi-resource-gen/src/generators/api-resource/render-token.ts b/tools/openapi-resource-gen/src/generators/api-resource/render-token.ts
@@ -95,7 +95,8 @@ export function renderTokenFile(
   if (providedIn === 'none') coreImports.push('FactoryProvider');
   lines.push(`import { ${coreImports.join(', ')} } from '@angular/core';`);
   lines.push(`import { httpResource } from '@angular/common/http';`);
-  lines.push(`import type { paths } from '../schema.d';`);
+  const needsComponents = ep.discriminator?.variants.some((v) => v.schemaName) ?? false;
+  lines.push(`import type { paths${needsComponents ? ', components' : ''} } from '../schema.d';`);
   lines.push(`import { ${baseUrlToken} } from '../api-base-url.token';`);
   for (const scheme of applicableSchemes) {
     lines.push(`import { ${scheme.tokenName} } from '../${scheme.fileName}';`);
@@ -159,6 +160,33 @@ export function renderTokenFile(
     }
   }
 
+  // Discriminated union helpers — emitted when the primary response schema has a discriminator.
+  if (ep.discriminator && hasResponse) {
+    const { propertyName, variants, isArrayResponse } = ep.discriminator;
+    const keyLiterals = variants.map((v) => JSON.stringify(v.key)).join(' | ');
+    lines.push(`export type ${pascal}DiscriminatorKey = ${keyLiterals};`, '');
+
+    for (const v of variants) {
+      const variantPascal = toPascalCase(v.key);
+      let typeExpr: string;
+      if (v.schemaName) {
+        // Mapping-based: intersect component schema with a literal discriminant tag.
+        typeExpr = `components['schemas'][${JSON.stringify(v.schemaName)}] & { ${JSON.stringify(propertyName)}: ${JSON.stringify(v.key)} }`;
+      } else {
+        // Enum-based fallback: narrow the response union with Extract.
+        const base = isArrayResponse
+          ? `${pascal}Response extends (infer _I)[] ? _I : never`
+          : `${pascal}Response`;
+        typeExpr = `Extract<${base}, { ${JSON.stringify(propertyName)}: ${JSON.stringify(v.key)} }>`;
+      }
+      lines.push(`export type ${pascal}${variantPascal} = ${typeExpr};`, '');
+    }
+
+    const variantNames = variants.map((v) => `${pascal}${toPascalCase(v.key)}`).join(' | ');
+    const discriminatedExpr = isArrayResponse ? `(${variantNames})[]` : variantNames;
+    lines.push(`export type ${pascal}Discriminated = ${discriminatedExpr};`, '');
+  }
+
   const responseT = hasResponse ? `${pascal}Response` : 'unknown';
   const fnArgs = buildFnArgs(ep, pascal, isGet);
 
