@codewithagents/openapi-server 1.3.1 → 1.4.0

package/dist/plugins/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/plugins/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAoWhE,UAAU,aAAa;IACrB,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAsFD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,CAAC,QAAQ,EAC1B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CA8Df;AAkGD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,CAAC,QAAQ,EAC1B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAuDf;AAKD,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CA0DjG"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/plugins/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAgiBhE,UAAU,aAAa;IACrB,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AA8ZD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,CAAC,QAAQ,EAC1B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CA0Cf;AAKD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,CAAC,QAAQ,EAC1B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAmCf;AAKD,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAsCjG"}

package/dist/plugins/router.js

@@ -43,7 +43,7 @@ function deriveServiceName(spec) {
         .join('');
     if (pascal.length === 0)
         return 'ApiService';
-    // Guard against numeric-start identifiers (e.g. '1Password Connect' → '_1PasswordConnect')
+    // Guard against numeric-start identifiers (e.g. '1Password Connect' -> '_1PasswordConnect')
     const safePascal = /^[0-9]/.test(pascal) ? `_${pascal}` : pascal;
     if (safePascal.endsWith('Service'))
         return safePascal;
@@ -53,14 +53,14 @@ function deriveServiceName(spec) {
  * Converts a raw operationId into a valid camelCase JS identifier.
  * Handles kebab-case, snake_case, dots, spaces, parens, braces and other
  * non-alphanumeric separators found in real-world OpenAPI specs.
- * e.g. "post-applePay-sessions"   → "postApplePaySessions"
- * e.g. "calendar.calendars.insert" → "calendarCalendarsInsert"
- * e.g. "Get User Profile"          → "getUserProfile"
- * e.g. "forgotPassword(oneTimeCode)" → "forgotPasswordOneTimeCode"
+ * e.g. "post-applePay-sessions"   -> "postApplePaySessions"
+ * e.g. "calendar.calendars.insert" -> "calendarCalendarsInsert"
+ * e.g. "Get User Profile"          -> "getUserProfile"
+ * e.g. "forgotPassword(oneTimeCode)" -> "forgotPasswordOneTimeCode"
  */
 function sanitizeOperationId(id) {
     const parts = id
-        .replace(/'/g, '') // strip apostrophes without splitting ("user's" → "users")
+        .replace(/'/g, '') // strip apostrophes without splitting ("user's" -> "users")
         .split(/[^a-zA-Z0-9]+/) // split on any non-alphanumeric sequence
         .filter(Boolean);
     if (parts.length === 0)
@@ -150,6 +150,225 @@ function getQueryParams(operation, spec) {
     }
     return result;
 }
+/**
+ * Map a schema format string to a Zod chain modifier.
+ * Returns an empty string when no specific format validation is needed.
+ */
+function formatToZodModifier(format) {
+    switch (format) {
+        case 'uuid':
+            return '.uuid()';
+        case 'email':
+            return '.email()';
+        case 'uri':
+        case 'url':
+            return '.url()';
+        case 'date-time':
+            return '.datetime()';
+        default:
+            return '';
+    }
+}
+/**
+ * Build a Zod expression for a path parameter based on its schema.
+ * Returns undefined when the parameter does not need format validation
+ * (simple string with no format constraint or non-string types used as strings in URLs).
+ */
+function pathParamZodExpr(schema) {
+    if (schema === undefined || isRef(schema))
+        return undefined;
+    const s = schema;
+    if (s.type !== 'string')
+        return undefined;
+    const format = s.format;
+    if (format === undefined)
+        return undefined;
+    const modifier = formatToZodModifier(format);
+    if (modifier === '')
+        return undefined;
+    return `z.string()${modifier}`;
+}
+/**
+ * Build a Zod expression for a query or header parameter based on its schema.
+ * Number/integer types use z.number() (after coercion by extraction code).
+ * String types use z.string(). Boolean types use z.boolean().
+ * Appends .optional() for non-required params.
+ */
+function paramZodExpr(tsType, required, schema) {
+    let base;
+    if (tsType === 'number') {
+        base = 'z.number()';
+    }
+    else if (tsType === 'boolean') {
+        base = 'z.boolean()';
+    }
+    else {
+        // string
+        if (schema !== undefined && !isRef(schema)) {
+            const s = schema;
+            const format = s.format;
+            const modifier = format !== undefined ? formatToZodModifier(format) : '';
+            base = `z.string()${modifier}`;
+        }
+        else {
+            base = 'z.string()';
+        }
+    }
+    return required ? base : `${base}.optional()`;
+}
+/**
+ * Collect path parameters that have Zod format constraints.
+ * Only returns entries for params that need format validation (e.g. uuid).
+ * Simple string params with no format constraint are excluded.
+ */
+function getPathParamValidations(operation, spec, rawPathParamNames) {
+    const parameters = operation.parameters;
+    if (parameters === undefined)
+        return [];
+    // Build a name-to-zodExpr map from path params to avoid nested loops.
+    const zodByName = new Map();
+    for (const p of parameters) {
+        const resolved = resolveParam(p, spec);
+        if (resolved === undefined || resolved.in !== 'path')
+            continue;
+        const schema = resolved.schema;
+        const zodExpr = pathParamZodExpr(schema);
+        if (zodExpr !== undefined)
+            zodByName.set(resolved.name, zodExpr);
+    }
+    const result = [];
+    for (const rawName of rawPathParamNames) {
+        const zodExpr = zodByName.get(rawName);
+        if (zodExpr !== undefined)
+            result.push({ rawName, zodExpr });
+    }
+    return result;
+}
+/**
+ * Collect header parameters from an operation.
+ */
+function getHeaderParams(operation, spec) {
+    const parameters = operation.parameters;
+    if (parameters === undefined)
+        return [];
+    const result = [];
+    for (const p of parameters) {
+        const resolved = resolveParam(p, spec);
+        if (resolved === undefined || resolved.in !== 'header')
+            continue;
+        result.push({
+            rawName: resolved.name,
+            required: resolved.required === true,
+        });
+    }
+    return result;
+}
+/**
+ * Determine whether query params need a Zod validation block.
+ * Triggered when any param is required or has a non-string type (to catch NaN/invalid input).
+ */
+function queryParamsNeedValidation(queryParams) {
+    return queryParams.some((q) => q.required || q.tsType !== 'string');
+}
+/**
+ * Emit Zod validation lines for query parameters into the handler line buffer.
+ * Uses the already-extracted params object (after Number() coercion).
+ * Uses short variable name _qv to keep the 422 return line under Prettier's print width.
+ * @param indent - outer handler indent (e.g. '  ')
+ */
+function emitQueryValidation(lines, queryParams, indent) {
+    const inner = `${indent}  `;
+    const fieldIndent = `${indent}    `;
+    const fields = queryParams
+        .map((q) => {
+        const expr = paramZodExpr(q.tsType, q.required);
+        return `${fieldIndent}${q.name}: ${expr}`;
+    })
+        .join(',\n');
+    lines.push(`${inner}// Validate query parameters: returns 422 with Zod issues on failure`);
+    lines.push(`${inner}const _qv = z.object({`);
+    lines.push(fields);
+    lines.push(`${inner}}).safeParse(params)`);
+}
+/**
+ * Emit Zod validation lines for path parameters (format constraints) into the handler line buffer.
+ * Uses short variable name _pv to keep the 422 return line under Prettier's print width.
+ * @param indent - outer handler indent (e.g. '  ')
+ * @param framework - used to generate the correct param accessor syntax
+ */
+function emitPathValidation(lines, validations, indent, framework) {
+    const inner = `${indent}  `;
+    const fieldIndent = `${indent}    `;
+    const schemaFields = validations
+        .map((v) => {
+        const key = /[^a-zA-Z0-9_$]/.test(v.rawName) ? JSON.stringify(v.rawName) : v.rawName;
+        return `${fieldIndent}${key}: ${v.zodExpr}`;
+    })
+        .join(',\n');
+    const rawFields = validations
+        .map((v) => {
+        const key = /[^a-zA-Z0-9_$]/.test(v.rawName) ? JSON.stringify(v.rawName) : v.rawName;
+        let access;
+        if (framework === 'hono') {
+            access = `c.req.param(${JSON.stringify(v.rawName)})`;
+        }
+        else if (framework === 'express') {
+            access = `req.params[${JSON.stringify(v.rawName)}]`;
+        }
+        else {
+            access = /[^a-zA-Z0-9_$]/.test(v.rawName)
+                ? `req.params[${JSON.stringify(v.rawName)}]`
+                : `req.params.${v.rawName}`;
+        }
+        return `${fieldIndent}${key}: ${access}`;
+    })
+        .join(',\n');
+    lines.push(`${inner}// Validate path parameters: returns 422 with Zod issues on failure`);
+    lines.push(`${inner}const _pv = z.object({`);
+    lines.push(schemaFields);
+    lines.push(`${inner}}).safeParse({`);
+    lines.push(rawFields);
+    lines.push(`${inner}})`);
+}
+/**
+ * Emit Zod validation lines for header parameters into the handler line buffer.
+ * Uses short variable name _hv to keep the 422 return line under Prettier's print width.
+ * @param indent - outer handler indent (e.g. '  ')
+ * @param framework - used to generate the correct header accessor syntax
+ */
+function emitHeaderValidation(lines, headerParams, indent, framework) {
+    const inner = `${indent}  `;
+    const fieldIndent = `${indent}    `;
+    const schemaFields = headerParams
+        .map((h) => {
+        const key = JSON.stringify(h.rawName);
+        const expr = h.required ? 'z.string()' : 'z.string().optional()';
+        return `${fieldIndent}${key}: ${expr}`;
+    })
+        .join(',\n');
+    const rawFields = headerParams
+        .map((h) => {
+        const key = JSON.stringify(h.rawName);
+        let access;
+        if (framework === 'hono') {
+            access = `c.req.header(${key})`;
+        }
+        else if (framework === 'express') {
+            access = `req.headers[${key}] as string | undefined`;
+        }
+        else {
+            access = `req.headers[${key}]`;
+        }
+        return `${fieldIndent}${key}: ${access}`;
+    })
+        .join(',\n');
+    lines.push(`${inner}// Validate request headers: returns 422 with Zod issues on failure`);
+    lines.push(`${inner}const _hv = z.object({`);
+    lines.push(schemaFields);
+    lines.push(`${inner}}).safeParse({`);
+    lines.push(rawFields);
+    lines.push(`${inner}})`);
+}
 function getBodyInfo(operation) {
     const requestBody = operation.requestBody;
     if (requestBody === undefined)
@@ -205,7 +424,9 @@ function collectOperations(spec) {
                 continue;
             const methodName = deriveMethodName(operation.operationId, method, path);
             const pathParams = extractPathParamsFromPath(path);
+            const pathParamValidations = getPathParamValidations(operation, spec, pathParams);
             const queryParams = getQueryParams(operation, spec);
+            const headerParams = getHeaderParams(operation, spec);
             const bodyInfo = getBodyInfo(operation);
             const responseStatus = getResponseStatus(operation, method);
             operations.push({
@@ -214,7 +435,9 @@ function collectOperations(spec) {
                 path,
                 honoPath: toHonoPath(path),
                 pathParams,
+                pathParamValidations,
                 queryParams,
+                headerParams,
                 bodyInfo,
                 responseStatus,
             });
@@ -222,10 +445,53 @@ function collectOperations(spec) {
     }
     return operations;
 }
+/** Collect sorted body type names from all operations. */
+function collectSortedBodyTypes(operations) {
+    const bodyTypes = new Set();
+    for (const op of operations) {
+        if (op.bodyInfo?.typeName !== undefined)
+            bodyTypes.add(op.bodyInfo.typeName);
+    }
+    return Array.from(bodyTypes).sort();
+}
+/** Collect the subset of schemaNames actually used by the given operations. */
+function collectUsedSchemaNames(operations, schemaNames) {
+    const used = new Set();
+    for (const op of operations) {
+        const typeName = op.bodyInfo?.typeName;
+        if (typeName === undefined)
+            continue;
+        const schemaName = `${typeName}Schema`;
+        if (schemaNames.has(schemaName))
+            used.add(schemaName);
+    }
+    return used;
+}
+/**
+ * Collect body type names, used schema names, and whether Zod is needed.
+ * Shared by all three generator functions to avoid duplication.
+ */
+function collectGeneratorSetup(operations, options) {
+    const sortedBodyTypes = collectSortedBodyTypes(operations);
+    const usedSchemaNames = options?.schemaNames !== undefined
+        ? collectUsedSchemaNames(operations, options.schemaNames)
+        : new Set();
+    const needsZod = (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) ||
+        operationsNeedZodForParams(operations);
+    return { sortedBodyTypes, usedSchemaNames, needsZod };
+}
+// ── Hono route handler ────────────────────────────────────────────────────────
 // fallow-ignore-next-line complexity
 function buildRouteHandler(op, indent, schemaNames) {
     const lines = [];
-    lines.push(`${indent}app.${op.httpMethod}('${op.honoPath}', async (c) => {`);
+    lines.push(`${indent}app.${op.httpMethod}(${JSON.stringify(op.honoPath)}, async (c) => {`);
+    // Path param format validation (e.g. uuid)
+    if (op.pathParamValidations.length > 0) {
+        emitPathValidation(lines, op.pathParamValidations, indent, 'hono');
+        lines.push(`${indent}  if (!_pv.success) {`);
+        lines.push(`${indent}    return c.json({ error: 'Invalid path parameters', issues: _pv.error.issues }, 422)`);
+        lines.push(`${indent}  }`);
+    }
     // Query params extraction
     if (op.queryParams.length > 0) {
         const fields = op.queryParams
@@ -239,6 +505,20 @@ function buildRouteHandler(op, indent, schemaNames) {
         lines.push(`${indent}  const params = {`);
         lines.push(fields);
         lines.push(`${indent}  }`);
+        // Validate query params when there are required or typed (non-string) params
+        if (queryParamsNeedValidation(op.queryParams)) {
+            emitQueryValidation(lines, op.queryParams, indent);
+            lines.push(`${indent}  if (!_qv.success) {`);
+            lines.push(`${indent}    return c.json({ error: 'Invalid query parameters', issues: _qv.error.issues }, 422)`);
+            lines.push(`${indent}  }`);
+        }
+    }
+    // Header param validation
+    if (op.headerParams.length > 0) {
+        emitHeaderValidation(lines, op.headerParams, indent, 'hono');
+        lines.push(`${indent}  if (!_hv.success) {`);
+        lines.push(`${indent}    return c.json({ error: 'Invalid request headers', issues: _hv.error.issues }, 422)`);
+        lines.push(`${indent}  }`);
     }
     // Body extraction
     let bodyVarName = 'body';
@@ -260,7 +540,7 @@ function buildRouteHandler(op, indent, schemaNames) {
     // Build service call args
     const serviceArgs = [];
     for (const p of op.pathParams) {
-        serviceArgs.push(`c.req.param('${p}')`);
+        serviceArgs.push(`c.req.param(${JSON.stringify(p)})`);
     }
     if (op.bodyInfo !== undefined) {
         serviceArgs.push(bodyVarName);
@@ -283,11 +563,18 @@ function buildRouteHandler(op, indent, schemaNames) {
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
-// ── Express router generator ───────────────────────────────────────────────────
+// ── Express route handler ─────────────────────────────────────────────────────
 // fallow-ignore-next-line complexity
 function buildExpressRouteHandler(op, indent, schemaNames) {
     const lines = [];
-    lines.push(`${indent}router.${op.httpMethod}('${op.honoPath}', async (req: Request, res: Response) => {`);
+    lines.push(`${indent}router.${op.httpMethod}(${JSON.stringify(op.honoPath)}, async (req: Request, res: Response) => {`);
+    // Path param format validation (e.g. uuid)
+    if (op.pathParamValidations.length > 0) {
+        emitPathValidation(lines, op.pathParamValidations, indent, 'express');
+        lines.push(`${indent}  if (!_pv.success) {`);
+        lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid path parameters', issues: _pv.error.issues })`);
+        lines.push(`${indent}  }`);
+    }
     // Query params extraction
     if (op.queryParams.length > 0) {
         const fields = op.queryParams
@@ -304,6 +591,20 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
         lines.push(`${indent}  const params = {`);
         lines.push(fields);
         lines.push(`${indent}  }`);
+        // Validate query params when there are required or typed (non-string) params
+        if (queryParamsNeedValidation(op.queryParams)) {
+            emitQueryValidation(lines, op.queryParams, indent);
+            lines.push(`${indent}  if (!_qv.success) {`);
+            lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid query parameters', issues: _qv.error.issues })`);
+            lines.push(`${indent}  }`);
+        }
+    }
+    // Header param validation
+    if (op.headerParams.length > 0) {
+        emitHeaderValidation(lines, op.headerParams, indent, 'express');
+        lines.push(`${indent}  if (!_hv.success) {`);
+        lines.push(`${indent}    return void res.status(422).json({ error: 'Invalid request headers', issues: _hv.error.issues })`);
+        lines.push(`${indent}  }`);
     }
     // Body extraction, with optional Zod validation
     let bodyVarName = 'body';
@@ -350,63 +651,7 @@ function buildExpressRouteHandler(op, indent, schemaNames) {
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
-// fallow-ignore-next-line complexity
-export function generateExpressRouter(spec, options) {
-    const serviceName = deriveServiceName(spec);
-    const operations = collectOperations(spec);
-    // Collect body type names for import from models.js
-    const bodyTypes = new Set();
-    for (const op of operations) {
-        if (op.bodyInfo?.typeName !== undefined) {
-            bodyTypes.add(op.bodyInfo.typeName);
-        }
-    }
-    const sortedBodyTypes = Array.from(bodyTypes).sort();
-    // Collect which schema names are actually needed (only for ops with a matching schema)
-    const usedSchemaNames = new Set();
-    if (options?.schemaNames !== undefined) {
-        for (const op of operations) {
-            const typeName = op.bodyInfo?.typeName;
-            if (typeName !== undefined) {
-                const schemaName = `${typeName}Schema`;
-                if (options.schemaNames.has(schemaName)) {
-                    usedSchemaNames.add(schemaName);
-                }
-            }
-        }
-    }
-    const lines = [];
-    lines.push('// This file is auto-generated. Do not edit manually.');
-    lines.push('// Express: apply express.json() middleware before mounting this router so req.body is populated.');
-    lines.push('');
-    lines.push("import { Router } from 'express'");
-    lines.push("import type { Request, Response } from 'express'");
-    if (sortedBodyTypes.length > 0) {
-        lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
-    }
-    lines.push(`import type { ${serviceName} } from './service.js'`);
-    if (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
-        lines.push(`import { z } from 'zod'`);
-        const sortedUsedSchemas = Array.from(usedSchemaNames).sort();
-        lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
-    }
-    lines.push('');
-    lines.push(`export function createRouter(service: ${serviceName}): Router {`);
-    lines.push('  const router = Router()');
-    lines.push('');
-    for (const op of operations) {
-        lines.push(buildExpressRouteHandler(op, '  ', options?.schemaNames));
-        lines.push('');
-    }
-    lines.push('  return router');
-    lines.push('}');
-    lines.push('');
-    return {
-        filename: 'router.ts',
-        content: lines.join('\n'),
-    };
-}
-// ── Fastify router generator ───────────────────────────────────────────────────
+// ── Fastify route handler ─────────────────────────────────────────────────────
 // fallow-ignore-next-line complexity
 function buildFastifyRouteHandler(op, indent, schemaNames) {
     const lines = [];
@@ -435,13 +680,43 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
         genericParts.push(`Params: { ${paramFields} }`);
     }
     const generic = genericParts.length > 0 ? `<{ ${genericParts.join('; ')} }>` : '';
-    lines.push(`${indent}app.${op.httpMethod}${generic}('${op.honoPath}', async (req, reply) => {`);
+    lines.push(`${indent}app.${op.httpMethod}${generic}(${JSON.stringify(op.honoPath)}, async (req, reply) => {`);
+    // Path param format validation (e.g. uuid)
+    if (op.pathParamValidations.length > 0) {
+        emitPathValidation(lines, op.pathParamValidations, indent, 'fastify');
+        lines.push(`${indent}  if (!_pv.success) {`);
+        lines.push(`${indent}    return reply.status(422).send({`);
+        lines.push(`${indent}      error: 'Invalid path parameters',`);
+        lines.push(`${indent}      issues: _pv.error.issues,`);
+        lines.push(`${indent}    })`);
+        lines.push(`${indent}  }`);
+    }
     // Query params extraction
     if (op.queryParams.length > 0) {
         const fields = op.queryParams.map((q) => `    ${q.name}: req.query.${q.name}`).join(',\n');
         lines.push(`${indent}  const params = {`);
         lines.push(fields);
         lines.push(`${indent}  }`);
+        // Validate query params when there are required or typed (non-string) params
+        if (queryParamsNeedValidation(op.queryParams)) {
+            emitQueryValidation(lines, op.queryParams, indent);
+            lines.push(`${indent}  if (!_qv.success) {`);
+            lines.push(`${indent}    return reply.status(422).send({`);
+            lines.push(`${indent}      error: 'Invalid query parameters',`);
+            lines.push(`${indent}      issues: _qv.error.issues,`);
+            lines.push(`${indent}    })`);
+            lines.push(`${indent}  }`);
+        }
+    }
+    // Header param validation
+    if (op.headerParams.length > 0) {
+        emitHeaderValidation(lines, op.headerParams, indent, 'fastify');
+        lines.push(`${indent}  if (!_hv.success) {`);
+        lines.push(`${indent}    return reply.status(422).send({`);
+        lines.push(`${indent}      error: 'Invalid request headers',`);
+        lines.push(`${indent}      issues: _hv.error.issues,`);
+        lines.push(`${indent}    })`);
+        lines.push(`${indent}  }`);
     }
     // Body handling, with optional Zod validation
     let bodyVarName = 'req.body';
@@ -484,31 +759,67 @@ function buildFastifyRouteHandler(op, indent, schemaNames) {
     lines.push(`${indent}})`);
     return lines.join('\n');
 }
+// ── Zod import helpers ────────────────────────────────────────────────────────
+/**
+ * Returns true when any operation in the list generates param validation code
+ * that requires Zod (path format validation, required/typed query params, or header params).
+ */
+function operationsNeedZodForParams(operations) {
+    for (const op of operations) {
+        if (op.pathParamValidations.length > 0)
+            return true;
+        if (queryParamsNeedValidation(op.queryParams))
+            return true;
+        if (op.headerParams.length > 0)
+            return true;
+    }
+    return false;
+}
+// ── Express router generator ──────────────────────────────────────────────────
 // fallow-ignore-next-line complexity
-export function generateFastifyRouter(spec, options) {
+export function generateExpressRouter(spec, options) {
     const serviceName = deriveServiceName(spec);
     const operations = collectOperations(spec);
-    // Collect body type names for import from models.js
-    const bodyTypes = new Set();
-    for (const op of operations) {
-        if (op.bodyInfo?.typeName !== undefined) {
-            bodyTypes.add(op.bodyInfo.typeName);
-        }
+    const { sortedBodyTypes, usedSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
+    const lines = [];
+    lines.push('// This file is auto-generated. Do not edit manually.');
+    lines.push('// Express: apply express.json() middleware before mounting this router so req.body is populated.');
+    lines.push('');
+    lines.push("import { Router } from 'express'");
+    lines.push("import type { Request, Response } from 'express'");
+    if (sortedBodyTypes.length > 0) {
+        lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
-    const sortedBodyTypes = Array.from(bodyTypes).sort();
-    // Collect which schema names are actually needed (only for ops with a matching schema)
-    const usedSchemaNames = new Set();
-    if (options?.schemaNames !== undefined) {
-        for (const op of operations) {
-            const typeName = op.bodyInfo?.typeName;
-            if (typeName !== undefined) {
-                const schemaName = `${typeName}Schema`;
-                if (options.schemaNames.has(schemaName)) {
-                    usedSchemaNames.add(schemaName);
-                }
-            }
-        }
+    lines.push(`import type { ${serviceName} } from './service.js'`);
+    if (needsZod) {
+        lines.push(`import { z } from 'zod'`);
     }
+    if (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
+        const sortedUsedSchemas = Array.from(usedSchemaNames).sort();
+        lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
+    }
+    lines.push('');
+    lines.push(`export function createRouter(service: ${serviceName}): Router {`);
+    lines.push('  const router = Router()');
+    lines.push('');
+    for (const op of operations) {
+        lines.push(buildExpressRouteHandler(op, '  ', options?.schemaNames));
+        lines.push('');
+    }
+    lines.push('  return router');
+    lines.push('}');
+    lines.push('');
+    return {
+        filename: 'router.ts',
+        content: lines.join('\n'),
+    };
+}
+// ── Fastify router generator ──────────────────────────────────────────────────
+// fallow-ignore-next-line complexity
+export function generateFastifyRouter(spec, options) {
+    const serviceName = deriveServiceName(spec);
+    const operations = collectOperations(spec);
+    const { sortedBodyTypes, usedSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
     const lines = [];
     lines.push('// This file is auto-generated. Do not edit manually.');
     lines.push('');
@@ -517,8 +828,10 @@ export function generateFastifyRouter(spec, options) {
         lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
     lines.push(`import type { ${serviceName} } from './service.js'`);
-    if (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
+    if (needsZod) {
         lines.push(`import { z } from 'zod'`);
+    }
+    if (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
         const sortedUsedSchemas = Array.from(usedSchemaNames).sort();
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }
@@ -540,27 +853,7 @@ export function generateFastifyRouter(spec, options) {
 export function generateRouter(spec, options) {
     const serviceName = deriveServiceName(spec);
     const operations = collectOperations(spec);
-    // Collect body type names for import from models.js
-    const bodyTypes = new Set();
-    for (const op of operations) {
-        if (op.bodyInfo?.typeName !== undefined) {
-            bodyTypes.add(op.bodyInfo.typeName);
-        }
-    }
-    const sortedBodyTypes = Array.from(bodyTypes).sort();
-    // Collect which schema names are actually needed (only for ops with a matching schema)
-    const usedSchemaNames = new Set();
-    if (options?.schemaNames !== undefined) {
-        for (const op of operations) {
-            const typeName = op.bodyInfo?.typeName;
-            if (typeName !== undefined) {
-                const schemaName = `${typeName}Schema`;
-                if (options.schemaNames.has(schemaName)) {
-                    usedSchemaNames.add(schemaName);
-                }
-            }
-        }
-    }
+    const { sortedBodyTypes, usedSchemaNames, needsZod } = collectGeneratorSetup(operations, options);
     const lines = [];
     lines.push('// This file is auto-generated. Do not edit manually.');
     lines.push('');
@@ -569,8 +862,10 @@ export function generateRouter(spec, options) {
         lines.push(`import type { ${sortedBodyTypes.join(', ')} } from './models.js'`);
     }
     lines.push(`import type { ${serviceName} } from './service.js'`);
-    if (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
+    if (needsZod) {
         lines.push(`import { z } from 'zod'`);
+    }
+    if (usedSchemaNames.size > 0 && options?.schemaImportPath !== undefined) {
         const sortedUsedSchemas = Array.from(usedSchemaNames).sort();
         lines.push(`import { ${sortedUsedSchemas.join(', ')} } from '${options.schemaImportPath}'`);
     }