feat(openapi-resource-gen): generate webhook token files for OAS 3.1 webhooks

Reads the top-level webhooks field from OAS 3.1 specs and emits one
<name>.webhook.ts per operation: InjectionToken<HttpInterceptorFn> plus
typed XxxWebhookPayload / XxxWebhookResponse aliases sourced from the
generated webhooks type in schema.d.ts. Webhook files are re-exported
from the root index barrel and included in stale-file cleanup. The paths
validator is loosened to accept specs that have webhooks but no paths.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: constantant

tools/openapi-resource-gen/src/generators/api-resource/endpoint-model.ts

@@ -12,6 +12,22 @@ export interface DiscriminatorModel {
   isArrayResponse: boolean;
 }
 
+export interface WebhookModel {
+  /** The webhook name key as it appears in the spec, e.g. 'newPet'. */
+  name: string;
+  /** HTTP method of the webhook operation, e.g. 'post'. */
+  method: string;
+  /** SCREAMING_SNAKE token constant name, e.g. 'NEW_PET_WEBHOOK'. */
+  tokenName: string;
+  /** Kebab-case file name without extension, e.g. 'new-pet.webhook'. */
+  fileName: string;
+  deprecated: boolean;
+  /** Content type of the request body, null if absent or non-JSON. */
+  payloadContentType: string | null;
+  /** 2xx response codes that carry application/json content. */
+  responseStatuses: string[];
+}
+
 /** Non-default serialization style for a query parameter. */
 export type QueryParamSerializer = 'deepObject' | 'csv' | 'pipes' | 'spaces';
 

tools/openapi-resource-gen/src/generators/api-resource/generator.spec.ts

@@ -1061,6 +1061,97 @@ describe('api-resource generator', () => {
     });
   });
 
+  describe('webhook generation', () => {
+    const WEBHOOK_SPEC = {
+      paths: {},
+      webhooks: {
+        newPet: {
+          post: {
+            requestBody: { content: { 'application/json': { schema: {} } } },
+            responses: {
+              '200': { content: { 'application/json': { schema: {} } } },
+            },
+          },
+        },
+      },
+    };
+
+    it('emits a .webhook.ts file with InjectionToken<HttpInterceptorFn>', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(WEBHOOK_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/wh-basic/src',
+      });
+      const content = tree.read('libs/wh-basic/src/new-pet.webhook.ts', 'utf-8')!;
+      expect(content).toContain('InjectionToken<HttpInterceptorFn>');
+      expect(content).toContain('NEW_PET_WEBHOOK');
+    });
+
+    it('emits XxxWebhookPayload type when requestBody has application/json', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(WEBHOOK_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/wh-payload/src',
+      });
+      const content = tree.read('libs/wh-payload/src/new-pet.webhook.ts', 'utf-8')!;
+      expect(content).toContain('NewPetWebhookPayload');
+      expect(content).toContain("webhooks['newPet']['post']");
+      expect(content).toContain("import type { webhooks } from './schema.d'");
+    });
+
+    it('emits XxxWebhookResponse type when 2xx response has application/json', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(WEBHOOK_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/wh-response/src',
+      });
+      const content = tree.read('libs/wh-response/src/new-pet.webhook.ts', 'utf-8')!;
+      expect(content).toContain('NewPetWebhookResponse');
+      expect(content).toContain("['responses']['200']");
+    });
+
+    it('re-exports webhook file from the root index barrel', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue(WEBHOOK_SPEC as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/wh-barrel/src',
+      });
+      const index = tree.read('libs/wh-barrel/src/index.ts', 'utf-8')!;
+      expect(index).toContain("export * from './new-pet.webhook'");
+    });
+
+    it('omits webhooks import when no payload or response schemas exist', async () => {
+      vi.mocked(SwaggerParser.dereference).mockResolvedValue({
+        paths: {},
+        webhooks: {
+          ping: {
+            post: {
+              responses: { '204': {} }, // no JSON content
+            },
+          },
+        },
+      } as never);
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/wh-notypes/src',
+      });
+      const content = tree.read('libs/wh-notypes/src/ping.webhook.ts', 'utf-8')!;
+      expect(content).toContain('PING_WEBHOOK');
+      expect(content).not.toContain("from './schema.d'");
+      expect(content).not.toContain('WebhookPayload');
+      expect(content).not.toContain('WebhookResponse');
+    });
+
+    it('does not emit webhook files for specs without webhooks field', async () => {
+      await apiResourceGenerator(tree, {
+        specPath: 'specs/petstore.yaml',
+        outputDir: 'libs/wh-empty/src',
+      });
+      const files = tree.listChanges().map((c) => c.path);
+      expect(files.some((f) => f.endsWith('.webhook.ts'))).toBe(false);
+    });
+  });
+
   describe('descriptive errors', () => {
     it('error message for missing openapi field includes version guidance', () => {
       // Verify the error text is descriptive before we even hit SwaggerParser.

tools/openapi-resource-gen/src/generators/api-resource/generator.ts

@@ -22,8 +22,8 @@ import * as path from 'path';
 import { pathToFileURL } from 'url';
 import SwaggerParser from '@apidevtools/swagger-parser';
 import { OpenAPIV3 } from 'openapi-types';
-import { buildEndpoints, parseSecuritySchemes } from './parse-spec';
-import { renderTokenFile, renderSecurityTokenFile } from './render-token';
+import { buildEndpoints, parseSecuritySchemes, parseWebhooks } from './parse-spec';
+import { renderTokenFile, renderSecurityTokenFile, renderWebhookTokenFile } from './render-token';
 import { renderMockFile } from './render-mock-file';
 import type { SecuritySchemeModel } from './endpoint-model';
 
@@ -181,6 +181,7 @@ export async function apiResourceGenerator(
       (f) =>
         f.endsWith('.token.ts') ||
         f.endsWith('.security-token.ts') ||
+        f.endsWith('.webhook.ts') ||
         f.endsWith('.mock.ts') ||
         f.endsWith('mocks.manifest.json') ||
         f.endsWith('/index.ts') ||
@@ -231,9 +232,11 @@ export async function apiResourceGenerator(
       `For Swagger 2.x specs, convert first with swagger2openapi.`
     );
   }
-  if (!specObj['paths'] || typeof specObj['paths'] !== 'object') {
+  const hasPaths = specObj['paths'] && typeof specObj['paths'] === 'object';
+  const hasWebhooks = specObj['webhooks'] && typeof specObj['webhooks'] === 'object';
+  if (!hasPaths && !hasWebhooks) {
     throw new Error(
-      `No "paths" object found in spec. Is "${specPath}" a valid OpenAPI 3.x file?`
+      `No "paths" or "webhooks" object found in spec. Is "${specPath}" a valid OpenAPI 3.x file?`
     );
   }
 
@@ -288,6 +291,14 @@ export async function apiResourceGenerator(
       writtenFiles.add(filePath);
     }
 
+    // 5b. Parse and emit webhook token files (OAS 3.1 webhooks).
+    const webhookModels = parseWebhooks(api, namingConvention);
+    for (const wh of webhookModels) {
+      const filePath = joinPathFragments(outputDir, `${wh.fileName}.ts`);
+      tree.write(filePath, renderWebhookTokenFile(wh));
+      writtenFiles.add(filePath);
+    }
+
     const endpoints = buildEndpoints(api, allowedTags, namingConvention);
 
     // 6. Group by tag
@@ -336,6 +347,7 @@ export async function apiResourceGenerator(
     const rootBarrel =
       `export * from './api-base-url.token';\n` +
       securitySchemes.map((s) => `export * from './${s.fileName}';\n`).join('') +
+      webhookModels.map((wh) => `export * from './${wh.fileName}';\n`).join('') +
       [...byTag.keys()].map((tag) => `export * from './${tag}';\n`).join('');
     const rootBarrelPath = joinPathFragments(outputDir, 'index.ts');
     tree.write(rootBarrelPath, rootBarrel);

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 { DiscriminatorModel, DiscriminatorVariant, EndpointModel, SecurityKind, SecuritySchemeModel, SpecialQueryParam } from './endpoint-model';
+import type { DiscriminatorModel, DiscriminatorVariant, EndpointModel, SecurityKind, SecuritySchemeModel, SpecialQueryParam, WebhookModel } from './endpoint-model';
 
 const HTTP_METHODS: ReadonlyArray<OpenAPIV3.HttpMethods> = [
   OpenAPIV3.HttpMethods.GET,
@@ -73,6 +73,8 @@ export function parseSecuritySchemes(api: OpenAPIV3.Document): SecuritySchemeMod
   return result;
 }
 
+const RESPONSE_PRIORITY_CODES = ['200', '201', '202', '206', '2XX', '203', '207', '208', '226'];
+
 function extractDiscriminatorFromSchema(
   schema: OpenAPIV3.SchemaObject | null | undefined,
   isArrayResponse: boolean
@@ -196,12 +198,11 @@ export function buildEndpoints(
         bodyContentType !== null && !KNOWN_BODY_CONTENT_TYPES.includes(bodyContentType);
 
       // 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 = [
-        ...RESPONSE_PRIORITY.filter((c) => allResponseCodes.includes(c)),
+        ...RESPONSE_PRIORITY_CODES.filter((c) => allResponseCodes.includes(c)),
         ...allResponseCodes.filter(
-          (c) => !RESPONSE_PRIORITY.includes(c) && /^2/.test(c)
+          (c) => !RESPONSE_PRIORITY_CODES.includes(c) && /^2/.test(c)
         ),
       ];
       const responseStatuses = orderedCodes.filter((code) => {
@@ -261,6 +262,54 @@ export function buildEndpoints(
   return endpoints;
 }
 
+/** Extract WebhookModel entries from api.webhooks (OAS 3.1). */
+export function parseWebhooks(
+  api: OpenAPIV3.Document,
+  namingConvention: 'camel' | 'kebab'
+): WebhookModel[] {
+  const webhooks = (api as unknown as { webhooks?: Record<string, OpenAPIV3.PathItemObject> })
+    .webhooks;
+  if (!webhooks) return [];
+
+  const result: WebhookModel[] = [];
+  for (const [name, pathItem] of Object.entries(webhooks)) {
+    if (!pathItem) continue;
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+      if (!operation) continue;
+
+      const fileName =
+        (namingConvention === 'kebab' ? toKebabCase(name) : name) + '.webhook';
+      const tokenName = toScreamingSnake(name) + '_WEBHOOK';
+
+      const requestBody = operation.requestBody as OpenAPIV3.RequestBodyObject | undefined;
+      const payloadContentType =
+        requestBody?.content?.['application/json'] != null ? 'application/json' : null;
+
+      const allResponseCodes = Object.keys(operation.responses ?? {});
+      const orderedCodes = [
+        ...RESPONSE_PRIORITY_CODES.filter((c) => allResponseCodes.includes(c)),
+        ...allResponseCodes.filter((c) => !RESPONSE_PRIORITY_CODES.includes(c) && /^2/.test(c)),
+      ];
+      const responseStatuses = orderedCodes.filter((code) => {
+        const obj = operation.responses?.[code] as OpenAPIV3.ResponseObject | undefined;
+        return obj?.content?.['application/json'] != null;
+      });
+
+      result.push({
+        name,
+        method,
+        tokenName,
+        fileName,
+        deprecated: operation.deprecated === true,
+        payloadContentType,
+        responseStatuses,
+      });
+    }
+  }
+  return result;
+}
+
 /** Convenience wrapper that dereferences the spec before building endpoints. */
 export async function parseSpec(
   specPath: string,

tools/openapi-resource-gen/src/generators/api-resource/render-token.ts

@@ -1,4 +1,4 @@
-import type { EndpointModel, SecuritySchemeModel } from './endpoint-model';
+import type { EndpointModel, SecuritySchemeModel, WebhookModel } from './endpoint-model';
 
 export function toPascalCase(str: string): string {
   return str
@@ -69,6 +69,57 @@ export function renderSecurityTokenFile(
   ].join('\n');
 }
 
+export function renderWebhookTokenFile(wh: WebhookModel): string {
+  const pascal = toPascalCase(wh.name);
+  const hasPayload = wh.payloadContentType !== null;
+  const hasResponse = wh.responseStatuses.length > 0;
+  const needsWebhooksType = hasPayload || hasResponse;
+
+  const lines: string[] = [];
+  lines.push(`import { InjectionToken } from '@angular/core';`);
+  lines.push(`import { HttpInterceptorFn } from '@angular/common/http';`);
+  if (needsWebhooksType) {
+    lines.push(`import type { webhooks } from './schema.d';`);
+  }
+  lines.push('');
+
+  if (hasPayload) {
+    lines.push(
+      `export type ${pascal}WebhookPayload =`,
+      `  NonNullable<webhooks[${JSON.stringify(wh.name)}][${JSON.stringify(wh.method)}]['requestBody']>['content'][${JSON.stringify(wh.payloadContentType)}];`,
+      ''
+    );
+  }
+
+  if (hasResponse) {
+    if (wh.responseStatuses.length === 1) {
+      lines.push(
+        `export type ${pascal}WebhookResponse =`,
+        `  webhooks[${JSON.stringify(wh.name)}][${JSON.stringify(wh.method)}]['responses'][${JSON.stringify(wh.responseStatuses[0])}]['content']['application/json'];`,
+        ''
+      );
+    } else {
+      lines.push(`export type ${pascal}WebhookResponse =`);
+      for (const code of wh.responseStatuses) {
+        lines.push(
+          `  | webhooks[${JSON.stringify(wh.name)}][${JSON.stringify(wh.method)}]['responses'][${JSON.stringify(code)}]['content']['application/json']`
+        );
+      }
+      lines.push('');
+    }
+  }
+
+  if (wh.deprecated) {
+    lines.push('/** @deprecated */');
+  }
+  lines.push(
+    `export const ${wh.tokenName} = new InjectionToken<HttpInterceptorFn>('${wh.tokenName}');`,
+    ''
+  );
+
+  return lines.join('\n');
+}
+
 export function renderTokenFile(
   ep: EndpointModel,
   baseUrlToken: string,