feat(openapi-resource-gen): deprecated JSDoc, response unions, binary body, cookie params, verbose flag

constantant · claude · constantant · commit fde686377de3 · 2026-06-13T21:49:18.000+02:00
- @deprecated JSDoc emitted above the InjectionToken constant when the OpenAPI operation has `deprecated: true` - Response type unions: collect all 2xx JSON response codes and emit a union type alias when multiple codes exist (e.g. 200 | 201 responses) - Binary body: non-json/form/multipart content types (octet-stream, pdf, image/*) emit `Blob | ArrayBuffer` instead of the paths type, which is the correct Angular HttpClient body type for binary uploads - Cookie params: `in: cookie` parameters are surfaced as named string args (after header params) and combined into a single Cookie header value; optional cookies use a conditional spread so absent values are omitted - Verbose flag: --verbose prints a +/~/- summary of created, updated, and deleted files after generation using tree.listChanges() Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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
@@ -25,13 +25,19 @@ export interface EndpointModel {
   apiPath: string;
   pathParams: string[];
   headerParams: Array<{ name: string; required: boolean }>;
+  cookieParams: Array<{ name: string; required: boolean }>;
   tokenName: string;
   fileName: string;
   hasQueryParams: boolean;
   hasBody: boolean;
   hasResponse: boolean;
-  responseStatus: string | null;
+  /** All 2xx response codes that carry application/json content, in priority order. */
+  responseStatuses: string[];
   bodyContentType: string | null;
+  /** True when bodyContentType is not json / form-urlencoded / multipart (e.g. octet-stream, pdf, image). */
+  isBinaryBody: boolean;
+  /** True when the operation is marked deprecated in the spec. */
+  deprecated: boolean;
   /** Names of security schemes that apply to this endpoint (resolved from global + operation level). */
   securitySchemeNames: string[];
 }
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
@@ -396,6 +396,210 @@ describe('api-resource generator', () => {
     });
   });
 
+  describe('deprecated operations', () => {
+    it('emits /** @deprecated */ JSDoc on a deprecated token', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/old-resource': {
+            get: {
+              operationId: 'legacyGet',
+              tags: ['legacy'],
+              deprecated: true,
+              responses: { '200': { content: { 'application/json': { schema: {} } } } },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/deprecated/src',
+      });
+      const content = tree.read('libs/deprecated/src/legacy/legacy-get.token.ts', 'utf-8')!;
+      expect(content).toContain('/** @deprecated */');
+    });
+
+    it('does NOT emit @deprecated for a non-deprecated operation', async () => {
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/not-deprecated/src',
+      });
+      const content = tree.read('libs/not-deprecated/src/pets/list-pets.token.ts', 'utf-8')!;
+      expect(content).not.toContain('@deprecated');
+    });
+  });
+
+  describe('response type unions', () => {
+    it('emits a union type when an endpoint returns 200 and 201 JSON responses', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/resources': {
+            put: {
+              operationId: 'upsertResource',
+              tags: ['resources'],
+              requestBody: { content: { 'application/json': { schema: {} } } },
+              responses: {
+                '200': { content: { 'application/json': { schema: {} } } },
+                '201': { content: { 'application/json': { schema: {} } } },
+              },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/union/src',
+      });
+      const content = tree.read('libs/union/src/resources/upsert-resource.token.ts', 'utf-8')!;
+      expect(content).toContain("['responses']['200']['content']['application/json']");
+      expect(content).toContain("['responses']['201']['content']['application/json']");
+      // The union pipe character should appear in the type definition
+      expect(content).toMatch(/\|\s*paths\[/);
+    });
+
+    it('emits a single type when only one 2xx JSON response exists', async () => {
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/single-resp/src',
+      });
+      const content = tree.read('libs/single-resp/src/pets/list-pets.token.ts', 'utf-8')!;
+      // Single status — no leading pipe in the type alias line
+      expect(content).toContain("export type ListPetsResponse =");
+      expect(content).toContain("['responses']['200']");
+      expect(content).not.toMatch(/export type ListPetsResponse =\s*\|/);
+    });
+  });
+
+  describe('binary body', () => {
+    it('emits Blob | ArrayBuffer for octet-stream request body', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/upload': {
+            post: {
+              operationId: 'uploadBinary',
+              tags: ['upload'],
+              requestBody: {
+                content: { 'application/octet-stream': { schema: { type: 'string', format: 'binary' } } },
+              },
+              responses: { '200': { content: { 'application/json': { schema: {} } } } },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/binary/src',
+      });
+      const content = tree.read('libs/binary/src/upload/upload-binary.token.ts', 'utf-8')!;
+      expect(content).toContain('Blob | ArrayBuffer');
+      // Must NOT reference the paths type for the body (would be wrong for binary)
+      expect(content).not.toContain("['requestBody']['content']['application/octet-stream']");
+    });
+
+    it('does not emit binary body type for standard json body', async () => {
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/json-body/src',
+      });
+      const content = tree.read('libs/json-body/src/pets/create-pet.token.ts', 'utf-8')!;
+      expect(content).not.toContain('Blob | ArrayBuffer');
+      // Prettier may split the long path across lines, so check the key parts separately
+      expect(content).toContain("requestBody']");
+      expect(content).toContain("['content']['application/json']");
+    });
+  });
+
+  describe('cookie parameters', () => {
+    it('adds required cookie param as a required function arg and Cookie header', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/me': {
+            get: {
+              operationId: 'getCurrentUser',
+              tags: ['user'],
+              parameters: [
+                { in: 'cookie', name: 'session', required: true, schema: { type: 'string' } },
+              ],
+              responses: { '200': { content: { 'application/json': { schema: {} } } } },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/cookies/src',
+      });
+      const content = tree.read('libs/cookies/src/user/get-current-user.token.ts', 'utf-8')!;
+      expect(content).toContain('session: string');
+      // Prettier strips quotes from valid identifier keys: 'Cookie' → Cookie
+      expect(content).toContain('Cookie:');
+      expect(content).toContain('session=');
+    });
+
+    it('adds optional cookie param with conditional spread in Cookie header', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {
+          '/prefs': {
+            get: {
+              operationId: 'getPreferences',
+              tags: ['prefs'],
+              parameters: [
+                { in: 'cookie', name: 'theme', required: false, schema: { type: 'string' } },
+              ],
+              responses: { '200': { content: { 'application/json': { schema: {} } } } },
+            },
+          },
+        },
+      } as never);
+
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/cookies-opt/src',
+      });
+      const content = tree.read('libs/cookies-opt/src/prefs/get-preferences.token.ts', 'utf-8')!;
+      expect(content).toContain('theme?: string');
+      // Prettier strips quotes from valid identifier keys: 'Cookie' → Cookie
+      expect(content).toContain('Cookie:');
+      // Optional cookie uses the conditional spread pattern
+      expect(content).toContain('theme != null');
+    });
+  });
+
+  describe('verbose output', () => {
+    it('prints a file summary when verbose is true', async () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+      try {
+        await apiResourceGenerator(tree, {
+          specPath: 'specs/petstore.yaml',
+          outputDir: 'libs/verbose/src',
+          verbose: true,
+        });
+        expect(consoleSpy).toHaveBeenCalled();
+        const output = consoleSpy.mock.calls.flat().join('\n');
+        expect(output).toContain('[openapi-resource-gen]');
+        expect(output).toContain('+');
+      } finally {
+        consoleSpy.mockRestore();
+      }
+    });
+
+    it('does not print anything when verbose is false', async () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+      try {
+        await apiResourceGenerator(tree, {
+          specPath: 'specs/petstore.yaml',
+          outputDir: 'libs/quiet/src',
+        });
+        expect(consoleSpy).not.toHaveBeenCalled();
+      } finally {
+        consoleSpy.mockRestore();
+      }
+    });
+  });
+
   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/generator.ts b/tools/openapi-resource-gen/src/generators/api-resource/generator.ts
@@ -37,6 +37,8 @@ export interface ApiResourceGeneratorSchema {
   includeMocks?: boolean;
   /** Identifier embedded in MockResourceMeta and mocks.manifest.json. */
   specId?: string;
+  /** Print a summary of created, updated, and deleted files after generation. */
+  verbose?: boolean;
 }
 
 /** Derive a specId from the baseUrlToken: PETSTORE_BASE_URL → petstore */
@@ -377,6 +379,19 @@ export async function apiResourceGenerator(
   }
 
   await formatFiles(tree);
+
+  if (options.verbose) {
+    const changes = tree.listChanges();
+    const created = changes.filter((c) => c.type === 'CREATE');
+    const updated = changes.filter((c) => c.type === 'UPDATE');
+    const deleted = changes.filter((c) => c.type === 'DELETE');
+    const summary: string[] = ['\n[openapi-resource-gen] Generation complete:'];
+    if (created.length) summary.push(...created.map((c) => `  + ${c.path}`));
+    if (updated.length) summary.push(...updated.map((c) => `  ~ ${c.path}`));
+    if (deleted.length) summary.push(...deleted.map((c) => `  - ${c.path}`));
+    if (!created.length && !updated.length && !deleted.length) summary.push('  (no changes)');
+    console.log(summary.join('\n'));
+  }
 }
 
 export default apiResourceGenerator;
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
@@ -10,6 +10,13 @@ const HTTP_METHODS: ReadonlyArray<OpenAPIV3.HttpMethods> = [
   OpenAPIV3.HttpMethods.DELETE,
 ];
 
+/** Content types that Angular's HttpClient handles natively (no special body wrapping). */
+const KNOWN_BODY_CONTENT_TYPES = [
+  'application/json',
+  'application/x-www-form-urlencoded',
+  'multipart/form-data',
+];
+
 export function toScreamingSnake(str: string): string {
   return str
     .replace(/\//g, '_')
@@ -111,6 +118,10 @@ export function buildEndpoints(
         .filter((p) => p.in === 'header')
         .map((p) => ({ name: p.name, required: p.required === true }));
 
+      const cookieParams = allParams
+        .filter((p) => p.in === 'cookie')
+        .map((p) => ({ name: p.name, required: p.required === true }));
+
       const hasQueryParams = allParams.some((p) => p.in === 'query');
 
       // Operation-level security overrides global; [] means explicitly no security.
@@ -127,19 +138,16 @@ export function buildEndpoints(
         | OpenAPIV3.RequestBodyObject
         | undefined;
       const bodyContent = requestBody?.content ?? {};
-      const BODY_CONTENT_TYPES = [
-        'application/json',
-        'application/x-www-form-urlencoded',
-        'multipart/form-data',
-      ];
       const bodyContentType =
-        BODY_CONTENT_TYPES.find((ct) => bodyContent[ct]) ??
+        KNOWN_BODY_CONTENT_TYPES.find((ct) => bodyContent[ct]) ??
         Object.keys(bodyContent)[0] ??
         null;
       const hasBody = bodyContentType !== null;
+      // Binary: any content type not in the known set (e.g. octet-stream, pdf, image/*).
+      const isBinaryBody =
+        bodyContentType !== null && !KNOWN_BODY_CONTENT_TYPES.includes(bodyContentType);
 
-      // Pick the first 2xx response code that carries application/json content.
-      // Covers 200, 201, 202, 206, and the catch-all '2XX' used by some specs.
+      // Collect ALL 2xx response codes that carry application/json, in priority order.
       const RESPONSE_PRIORITY = ['200', '201', '202', '206', '2XX', '203', '207', '208', '226'];
       const allResponseCodes = Object.keys(operation.responses ?? {});
       const orderedCodes = [
@@ -148,12 +156,13 @@ export function buildEndpoints(
           (c) => !RESPONSE_PRIORITY.includes(c) && /^2/.test(c)
         ),
       ];
-      const responseStatus =
-        orderedCodes.find((code) => {
-          const obj = operation.responses?.[code] as OpenAPIV3.ResponseObject | undefined;
-          return obj?.content?.['application/json'] != null;
-        }) ?? null;
-      const hasResponse = responseStatus !== null;
+      const responseStatuses = orderedCodes.filter((code) => {
+        const obj = operation.responses?.[code] as OpenAPIV3.ResponseObject | undefined;
+        return obj?.content?.['application/json'] != null;
+      });
+      const hasResponse = responseStatuses.length > 0;
+
+      const deprecated = operation.deprecated === true;
 
       endpoints.push({
         tag: toKebabCase(tag),
@@ -162,13 +171,16 @@ export function buildEndpoints(
         apiPath,
         pathParams,
         headerParams,
+        cookieParams,
         tokenName,
         fileName,
         hasQueryParams,
         hasBody,
         hasResponse,
-        responseStatus,
+        responseStatuses,
         bodyContentType,
+        isBinaryBody,
+        deprecated,
         securitySchemeNames,
       });
     }
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
diff --git a/tools/openapi-resource-gen/src/generators/api-resource/schema.json b/tools/openapi-resource-gen/src/generators/api-resource/schema.json
