next-openapi-gen 0.9.4 → 0.10.1

package/README.md

@@ -4,9 +4,9 @@ Automatically generate OpenAPI 3.0 documentation from Next.js projects, with sup
 
 ## Features
 
-- ✅ Automatic OpenAPI 3.0 documentation generation from Next.js App Router
-- ✅ Multiple schema types: `TypeScript`, `Zod`, `Drizzle-Zod`, or `custom YAML/JSON` files 🆕
-- ✅ Mix schema sources simultaneously - perfect for gradual migrations 🆕
+- ✅ Automatic OpenAPI 3.0 documentation generation from Next.js App Router and Pages Router 🆕
+- ✅ Multiple schema types: `TypeScript`, `Zod`, `Drizzle-Zod`, or `custom YAML/JSON` files
+- ✅ Mix schema sources simultaneously - perfect for gradual migrations
 - ✅ JSDoc comments with intelligent parameter examples
 - ✅ Multiple UI interfaces: `Scalar`, `Swagger`, `Redoc`, `Stoplight`, and `RapiDoc` available at `/api-docs` url
 - ✅ Auto-detection of path parameters (e.g., `/users/[id]/route.ts`)
@@ -70,7 +70,8 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
       "description": "Local server"
     }
   ],
-  "apiDir": "src/app/api",
+  "apiDir": "src/app/api", // or "pages/api" for Pages Router
+  "routerType": "app", // "app" (default) or "pages" for legacy Pages Router
   "schemaDir": "src/types", // or "src/schemas" for Zod schemas
   "schemaType": "zod", // or "typescript", or ["zod", "typescript"] for multiple
   "schemaFiles": [], // Optional: ["./schemas/models.yaml", "./schemas/api.json"]
@@ -88,6 +89,7 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
 | Option                 | Description                                                                   |
 | ---------------------- | ----------------------------------------------------------------------------- |
 | `apiDir`               | Path to the API directory                                                     |
+| `routerType`           | Router type: `"app"` (default) or `"pages"` for legacy Pages Router           |
 | `schemaDir`            | Path to the types/schemas directory                                           |
 | `schemaType`           | Schema type: `"zod"`, `"typescript"`, or `["zod", "typescript"]` for multiple |
 | `schemaFiles`          | Optional: Array of custom OpenAPI schema files (YAML/JSON) to include         |
@@ -226,6 +228,16 @@ export async function POST(request: NextRequest) {
 | `@deprecated`          | Marks the route as deprecated                                                                                            |
 | `@openapi`             | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled)                                      |
 | `@ignore`              | Excludes the route from OpenAPI documentation                                                                            |
+| `@method`              | HTTP method for Pages Router (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) - required for Pages Router only                  |
+
+## Pages Router Support 🆕
+
+The library now supports the legacy Next.js Pages Router. To use it:
+
+1. Set `routerType` to `"pages"` in your configuration
+2. Use the `@method` JSDoc tag to specify HTTP methods
+
+See **[next15-pages-router](./examples/next15-pages-router)** for a complete working example.
 
 ## CLI Usage
 

package/dist/lib/app-router-strategy.js

@@ -0,0 +1,66 @@
+import * as t from "@babel/types";
+import fs from "fs";
+import traverseModule from "@babel/traverse";
+const traverse = traverseModule.default || traverseModule;
+import { HTTP_METHODS } from "./router-strategy.js";
+import { extractJSDocComments, parseTypeScriptFile } from "./utils.js";
+export class AppRouterStrategy {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    shouldProcessFile(fileName) {
+        return fileName === "route.ts" || fileName === "route.tsx";
+    }
+    processFile(filePath, addRoute) {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const ast = parseTypeScriptFile(content);
+        traverse(ast, {
+            ExportNamedDeclaration: (path) => {
+                const declaration = path.node.declaration;
+                if (t.isFunctionDeclaration(declaration) &&
+                    t.isIdentifier(declaration.id)) {
+                    if (HTTP_METHODS.includes(declaration.id.name)) {
+                        const dataTypes = extractJSDocComments(path);
+                        addRoute(declaration.id.name, filePath, dataTypes);
+                    }
+                }
+                if (t.isVariableDeclaration(declaration)) {
+                    declaration.declarations.forEach((decl) => {
+                        if (t.isVariableDeclarator(decl) && t.isIdentifier(decl.id)) {
+                            if (HTTP_METHODS.includes(decl.id.name)) {
+                                const dataTypes = extractJSDocComments(path);
+                                addRoute(decl.id.name, filePath, dataTypes);
+                            }
+                        }
+                    });
+                }
+            },
+        });
+    }
+    getRoutePath(filePath) {
+        const normalizedPath = filePath.replaceAll("\\", "/");
+        const normalizedApiDir = this.config.apiDir
+            .replaceAll("\\", "/")
+            .replace(/^\.\//, "")
+            .replace(/\/$/, "");
+        const apiDirIndex = normalizedPath.indexOf(normalizedApiDir);
+        if (apiDirIndex === -1) {
+            throw new Error(`Could not find apiDir "${this.config.apiDir}" in file path "${filePath}"`);
+        }
+        let relativePath = normalizedPath.substring(apiDirIndex + normalizedApiDir.length);
+        // Remove the /route.ts or /route.tsx suffix
+        relativePath = relativePath.replace(/\/route\.tsx?$/, "");
+        if (!relativePath.startsWith("/")) {
+            relativePath = "/" + relativePath;
+        }
+        relativePath = relativePath.replace(/\/$/, "");
+        // Remove Next.js route groups (folders in parentheses like (authenticated))
+        relativePath = relativePath.replace(/\/\([^)]+\)/g, "");
+        // Handle catch-all routes before dynamic routes
+        relativePath = relativePath.replace(/\/\[\.\.\.(.*?)\]/g, "/{$1}");
+        // Convert Next.js dynamic route syntax to OpenAPI parameter syntax
+        relativePath = relativePath.replace(/\/\[([^\]]+)\]/g, "/{$1}");
+        return relativePath || "/";
+    }
+}

package/dist/lib/drizzle-zod-processor.js

@@ -119,7 +119,6 @@ export class DrizzleZodProcessor {
                 ? node.callee.property.name
                 : null;
             if (methodName === "optional" ||
-                methodName === "nullable" ||
                 methodName === "nullish") {
                 return true;
             }
@@ -291,10 +290,13 @@ export class DrizzleZodProcessor {
                 result.type = "integer";
                 break;
             case "optional":
+                // Handled by isFieldOptional check, no schema modification needed
+                break;
             case "nullable":
+                result.nullable = true;
+                break;
             case "nullish":
-                // These are handled by the isFieldOptional check
-                // Don't modify the schema here
+                result.nullable = true;
                 break;
             case "describe":
                 if (args.length > 0 && t.isStringLiteral(args[0])) {

package/dist/lib/openapi-generator.js

@@ -17,9 +17,10 @@ export class OpenApiGenerator {
     }
     getConfig() {
         // @ts-ignore
-        const { apiDir, schemaDir, docsUrl, ui, outputFile, outputDir, includeOpenApiRoutes, ignoreRoutes, schemaType = "typescript", schemaFiles, defaultResponseSet, responseSets, errorConfig, debug } = this.template;
+        const { apiDir, routerType, schemaDir, docsUrl, ui, outputFile, outputDir, includeOpenApiRoutes, ignoreRoutes, schemaType = "typescript", schemaFiles, defaultResponseSet, responseSets, errorConfig, debug } = this.template;
         return {
             apiDir: apiDir || "./src/app/api",
+            routerType: routerType || "app",
             schemaDir: schemaDir || "./src",
             docsUrl: docsUrl || "api-docs",
             ui: ui || "scalar",

package/dist/lib/pages-router-strategy.js

@@ -0,0 +1,196 @@
+import fs from "fs";
+import traverseModule from "@babel/traverse";
+const traverse = traverseModule.default || traverseModule;
+import { HTTP_METHODS } from "./router-strategy.js";
+import { parseTypeScriptFile } from "./utils.js";
+export class PagesRouterStrategy {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    shouldProcessFile(fileName) {
+        return (!fileName.startsWith("_") &&
+            (fileName.endsWith(".ts") || fileName.endsWith(".tsx")));
+    }
+    processFile(filePath, addRoute) {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const ast = parseTypeScriptFile(content);
+        const methodComments = [];
+        traverse(ast, {
+            ExportDefaultDeclaration: (nodePath) => {
+                const allComments = ast.comments || [];
+                const exportStart = nodePath.node.start || 0;
+                allComments.forEach((comment) => {
+                    if (comment.type === "CommentBlock" &&
+                        (comment.end || 0) < exportStart) {
+                        const commentValue = comment.value;
+                        if (commentValue.includes("@method")) {
+                            const dataTypes = this.extractJSDocFromComment(commentValue);
+                            if (dataTypes.method && HTTP_METHODS.includes(dataTypes.method)) {
+                                methodComments.push({
+                                    method: dataTypes.method,
+                                    dataTypes,
+                                });
+                            }
+                        }
+                    }
+                });
+                methodComments.forEach(({ method, dataTypes }) => {
+                    addRoute(method, filePath, dataTypes);
+                });
+            },
+        });
+    }
+    getRoutePath(filePath) {
+        const normalizedPath = filePath.replaceAll("\\", "/");
+        const normalizedApiDir = this.config.apiDir
+            .replaceAll("\\", "/")
+            .replace(/^\.\//, "")
+            .replace(/\/$/, "");
+        const apiDirIndex = normalizedPath.indexOf(normalizedApiDir);
+        if (apiDirIndex === -1) {
+            throw new Error(`Could not find apiDir "${this.config.apiDir}" in file path "${filePath}"`);
+        }
+        let relativePath = normalizedPath.substring(apiDirIndex + normalizedApiDir.length);
+        // Remove the file extension (.ts or .tsx)
+        relativePath = relativePath.replace(/\.tsx?$/, "");
+        // Remove /index suffix (pages/api/users/index.ts -> /users)
+        relativePath = relativePath.replace(/\/index$/, "");
+        if (!relativePath.startsWith("/")) {
+            relativePath = "/" + relativePath;
+        }
+        relativePath = relativePath.replace(/\/$/, "");
+        // Handle catch-all routes before dynamic routes
+        relativePath = relativePath.replace(/\/\[\.\.\.(.*?)\]/g, "/{$1}");
+        // Convert Next.js dynamic route syntax to OpenAPI parameter syntax
+        relativePath = relativePath.replace(/\/\[([^\]]+)\]/g, "/{$1}");
+        return relativePath || "/";
+    }
+    /**
+     * Extract JSDoc data from a raw comment string (Pages Router specific)
+     */
+    extractJSDocFromComment(commentValue) {
+        const cleanedComment = commentValue.replace(/\*\s*/g, "").trim();
+        let tag = "";
+        let summary = "";
+        let description = "";
+        let paramsType = "";
+        let pathParamsType = "";
+        let bodyType = "";
+        let auth = "";
+        let isOpenApi = cleanedComment.includes("@openapi");
+        let isIgnored = cleanedComment.includes("@ignore");
+        let deprecated = cleanedComment.includes("@deprecated");
+        let bodyDescription = "";
+        let contentType = "";
+        let responseType = "";
+        let responseDescription = "";
+        let responseSet = "";
+        let addResponses = "";
+        let successCode = "";
+        let operationId = "";
+        let method = "";
+        const methodMatch = cleanedComment.match(/@method\s+(\S+)/);
+        if (methodMatch) {
+            method = methodMatch[1].trim().toUpperCase();
+        }
+        const firstLine = cleanedComment.split("\n")[0];
+        if (!firstLine.trim().startsWith("@")) {
+            summary = firstLine.trim();
+        }
+        const descMatch = cleanedComment.match(/@description\s+(.*)/);
+        if (descMatch) {
+            description = descMatch[1].trim();
+        }
+        const tagMatch = cleanedComment.match(/@tag\s+(.*)/);
+        if (tagMatch) {
+            tag = tagMatch[1].trim();
+        }
+        const paramsMatch = cleanedComment.match(/@queryParams\s+([\w<>,\s\[\]]+)/) ||
+            cleanedComment.match(/@params\s+([\w<>,\s\[\]]+)/);
+        if (paramsMatch) {
+            paramsType = paramsMatch[1].trim();
+        }
+        const pathParamsMatch = cleanedComment.match(/@pathParams\s+([\w<>,\s\[\]]+)/);
+        if (pathParamsMatch) {
+            pathParamsType = pathParamsMatch[1].trim();
+        }
+        const bodyMatch = cleanedComment.match(/@body\s+([\w<>,\s\[\]]+)/);
+        if (bodyMatch) {
+            bodyType = bodyMatch[1].trim();
+        }
+        const bodyDescMatch = cleanedComment.match(/@bodyDescription\s+(.*)/);
+        if (bodyDescMatch) {
+            bodyDescription = bodyDescMatch[1].trim();
+        }
+        const contentTypeMatch = cleanedComment.match(/@contentType\s+(.*)/);
+        if (contentTypeMatch) {
+            contentType = contentTypeMatch[1].trim();
+        }
+        const responseMatch = cleanedComment.match(/@response\s+(?:(\d+):)?([^@\n\r]+)/);
+        if (responseMatch) {
+            const [, code, type] = responseMatch;
+            const trimmedType = type?.trim();
+            if (!code && trimmedType && /^\d{3}$/.test(trimmedType)) {
+                successCode = trimmedType;
+                responseType = undefined;
+            }
+            else {
+                successCode = code || "";
+                responseType = trimmedType;
+            }
+        }
+        const respDescMatch = cleanedComment.match(/@responseDescription\s+(.*)/);
+        if (respDescMatch) {
+            responseDescription = respDescMatch[1].trim();
+        }
+        const respSetMatch = cleanedComment.match(/@responseSet\s+(.*)/);
+        if (respSetMatch) {
+            responseSet = respSetMatch[1].trim();
+        }
+        const addMatch = cleanedComment.match(/@add\s+(.*)/);
+        if (addMatch) {
+            addResponses = addMatch[1].trim();
+        }
+        const opIdMatch = cleanedComment.match(/@operationId\s+(\S+)/);
+        if (opIdMatch) {
+            operationId = opIdMatch[1].trim();
+        }
+        const authMatch = cleanedComment.match(/@auth\s+(.*)/);
+        if (authMatch) {
+            const authValue = authMatch[1].trim();
+            switch (authValue) {
+                case "bearer":
+                    auth = "BearerAuth";
+                    break;
+                case "basic":
+                    auth = "BasicAuth";
+                    break;
+                case "apikey":
+                    auth = "ApiKeyAuth";
+                    break;
+            }
+        }
+        return {
+            tag,
+            auth,
+            summary,
+            description,
+            paramsType,
+            pathParamsType,
+            bodyType,
+            isOpenApi,
+            isIgnored,
+            deprecated,
+            bodyDescription,
+            contentType,
+            responseType,
+            responseDescription,
+            responseSet,
+            addResponses,
+            successCode,
+            operationId,
+            method,
+        };
+    }
+}

package/dist/lib/route-processor.js

@@ -1,24 +1,25 @@
-import * as t from "@babel/types";
 import fs from "fs";
 import path from "path";
-import traverseModule from "@babel/traverse";
-// Handle both ES modules and CommonJS
-const traverse = traverseModule.default || traverseModule;
 import { SchemaProcessor } from "./schema-processor.js";
-import { capitalize, extractJSDocComments, parseTypeScriptFile, extractPathParameters, getOperationId, } from "./utils.js";
+import { capitalize, extractPathParameters, getOperationId, } from "./utils.js";
 import { logger } from "./logger.js";
-const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+import { AppRouterStrategy } from "./app-router-strategy.js";
+import { PagesRouterStrategy } from "./pages-router-strategy.js";
 const MUTATION_HTTP_METHODS = ["PATCH", "POST", "PUT"];
 export class RouteProcessor {
     swaggerPaths = {};
     schemaProcessor;
     config;
+    strategy;
     directoryCache = {};
     statCache = {};
     processFileTracker = {};
     constructor(config) {
         this.config = config;
         this.schemaProcessor = new SchemaProcessor(config.schemaDir, config.schemaType, config.schemaFiles);
+        this.strategy = config.routerType === "pages"
+            ? new PagesRouterStrategy(config)
+            : new AppRouterStrategy(config);
     }
     buildResponsesFromConfig(dataTypes, method) {
         const responses = {};
@@ -158,9 +159,6 @@ export class RouteProcessor {
     getSchemaProcessor() {
         return this.schemaProcessor;
     }
-    isRoute(varName) {
-        return HTTP_METHODS.includes(varName);
-    }
     /**
      * Check if a route should be ignored based on config patterns or @ignore tag
      */
@@ -181,65 +179,23 @@ export class RouteProcessor {
             return regex.test(routePath);
         });
     }
-    processFile(filePath) {
-        // Check if the file has already been processed
-        if (this.processFileTracker[filePath])
+    /**
+     * Register a discovered route after filtering
+     */
+    registerRoute(method, filePath, dataTypes) {
+        const routePath = this.strategy.getRoutePath(filePath);
+        if (this.shouldIgnoreRoute(routePath, dataTypes)) {
+            logger.debug(`Ignoring route: ${routePath}`);
             return;
-        const content = fs.readFileSync(filePath, "utf-8");
-        const ast = parseTypeScriptFile(content);
-        traverse(ast, {
-            ExportNamedDeclaration: (path) => {
-                const declaration = path.node.declaration;
-                if (t.isFunctionDeclaration(declaration) &&
-                    t.isIdentifier(declaration.id)) {
-                    const dataTypes = extractJSDocComments(path);
-                    if (this.isRoute(declaration.id.name)) {
-                        const routePath = this.getRoutePath(filePath);
-                        // Skip if route should be ignored
-                        if (this.shouldIgnoreRoute(routePath, dataTypes)) {
-                            logger.debug(`Ignoring route: ${routePath}`);
-                            return;
-                        }
-                        // Don't bother adding routes for processing if only including OpenAPI routes and the route is not OpenAPI
-                        if (!this.config.includeOpenApiRoutes ||
-                            (this.config.includeOpenApiRoutes && dataTypes.isOpenApi)) {
-                            // Check for URL parameters in the route path
-                            const pathParams = extractPathParameters(routePath);
-                            // If we have path parameters but no pathParamsType defined, we should log a warning
-                            if (pathParams.length > 0 && !dataTypes.pathParamsType) {
-                                logger.debug(`Route ${routePath} contains path parameters ${pathParams.join(", ")} but no @pathParams type is defined.`);
-                            }
-                            this.addRouteToPaths(declaration.id.name, filePath, dataTypes);
-                        }
-                    }
-                }
-                if (t.isVariableDeclaration(declaration)) {
-                    declaration.declarations.forEach((decl) => {
-                        if (t.isVariableDeclarator(decl) && t.isIdentifier(decl.id)) {
-                            if (this.isRoute(decl.id.name)) {
-                                const dataTypes = extractJSDocComments(path);
-                                const routePath = this.getRoutePath(filePath);
-                                // Skip if route should be ignored
-                                if (this.shouldIgnoreRoute(routePath, dataTypes)) {
-                                    logger.debug(`Ignoring route: ${routePath}`);
-                                    return;
-                                }
-                                // Don't bother adding routes for processing if only including OpenAPI routes and the route is not OpenAPI
-                                if (!this.config.includeOpenApiRoutes ||
-                                    (this.config.includeOpenApiRoutes && dataTypes.isOpenApi)) {
-                                    const pathParams = extractPathParameters(routePath);
-                                    if (pathParams.length > 0 && !dataTypes.pathParamsType) {
-                                        logger.debug(`Route ${routePath} contains path parameters ${pathParams.join(", ")} but no @pathParams type is defined.`);
-                                    }
-                                    this.addRouteToPaths(decl.id.name, filePath, dataTypes);
-                                }
-                            }
-                        }
-                    });
-                }
-            },
-        });
-        this.processFileTracker[filePath] = true;
+        }
+        if (this.config.includeOpenApiRoutes && !dataTypes.isOpenApi) {
+            return;
+        }
+        const pathParams = extractPathParameters(routePath);
+        if (pathParams.length > 0 && !dataTypes.pathParamsType) {
+            logger.debug(`Route ${routePath} contains path parameters ${pathParams.join(", ")} but no @pathParams type is defined.`);
+        }
+        this.addRouteToPaths(method, filePath, dataTypes);
     }
     scanApiRoutes(dir) {
         logger.debug(`Scanning API routes in: ${dir}`);
@@ -257,18 +213,20 @@ export class RouteProcessor {
             }
             if (stat.isDirectory()) {
                 this.scanApiRoutes(filePath);
-                // @ts-ignore
             }
-            else if (file.endsWith(".ts") || file.endsWith(".tsx")) {
-                if (file === "route.ts" || file === "route.tsx") {
-                    this.processFile(filePath);
+            else if (this.strategy.shouldProcessFile(file)) {
+                if (!this.processFileTracker[filePath]) {
+                    this.strategy.processFile(filePath, (method, fp, dataTypes) => {
+                        this.registerRoute(method, fp, dataTypes);
+                    });
+                    this.processFileTracker[filePath] = true;
                 }
             }
         });
     }
     addRouteToPaths(varName, filePath, dataTypes) {
         const method = varName.toLowerCase();
-        const routePath = this.getRoutePath(filePath);
+        const routePath = this.strategy.getRoutePath(filePath);
         const rootPath = capitalize(routePath.split("/")[1]);
         const operationId = dataTypes.operationId || getOperationId(routePath, method);
         const { tag, summary, description, auth, isOpenApi, deprecated, bodyDescription, responseDescription, } = dataTypes;
@@ -355,38 +313,6 @@ export class RouteProcessor {
         }
         this.swaggerPaths[routePath][method] = definition;
     }
-    getRoutePath(filePath) {
-        // Normalize path separators first
-        const normalizedPath = filePath.replaceAll("\\", "/");
-        // Normalize apiDir to ensure consistent format
-        const normalizedApiDir = this.config.apiDir
-            .replaceAll("\\", "/")
-            .replace(/^\.\//, "")
-            .replace(/\/$/, "");
-        // Find the apiDir position in the normalized path
-        const apiDirIndex = normalizedPath.indexOf(normalizedApiDir);
-        if (apiDirIndex === -1) {
-            throw new Error(`Could not find apiDir "${this.config.apiDir}" in file path "${filePath}"`);
-        }
-        // Extract the path after apiDir
-        let relativePath = normalizedPath.substring(apiDirIndex + normalizedApiDir.length);
-        // Remove the /route.ts or /route.tsx suffix
-        relativePath = relativePath.replace(/\/route\.tsx?$/, "");
-        // Ensure the path starts with /
-        if (!relativePath.startsWith("/")) {
-            relativePath = "/" + relativePath;
-        }
-        // Remove trailing slash
-        relativePath = relativePath.replace(/\/$/, "");
-        // Remove Next.js route groups (folders in parentheses like (authenticated), (marketing))
-        relativePath = relativePath.replace(/\/\([^)]+\)/g, "");
-        // Handle catch-all routes ([...param]) before converting dynamic routes
-        // This must come first because [...param] would also match the [param] pattern
-        relativePath = relativePath.replace(/\/\[\.\.\.(.*?)\]/g, "/{$1}");
-        // Convert Next.js dynamic route syntax to OpenAPI parameter syntax
-        relativePath = relativePath.replace(/\/\[([^\]]+)\]/g, "/{$1}");
-        return relativePath || "/";
-    }
     getSortedPaths(paths) {
         function comparePaths(a, b) {
             const aMethods = this.swaggerPaths[a] || {};

package/dist/lib/router-strategy.js

@@ -0,0 +1 @@
+export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];

package/dist/lib/utils.js

@@ -35,6 +35,7 @@ export function extractJSDocComments(path) {
     let addResponses = "";
     let successCode = "";
     let operationId = "";
+    let method = "";
     if (comments) {
         comments.forEach((comment) => {
             const commentValue = cleanComment(comment.value);
@@ -133,6 +134,13 @@ export function extractJSDocComments(path) {
                     operationId = match[1].trim();
                 }
             }
+            if (commentValue.includes("@method")) {
+                const regex = /@method\s+(\S+)/;
+                const match = commentValue.match(regex);
+                if (match && match[1]) {
+                    method = match[1].trim().toUpperCase();
+                }
+            }
             if (commentValue.includes("@response")) {
                 // Updated regex to support generic types
                 const responseMatch = commentValue.match(/@response\s+(?:(\d+):)?([^@\n\r]+)(?:\s+(.*))?/);
@@ -175,6 +183,7 @@ export function extractJSDocComments(path) {
         addResponses,
         successCode,
         operationId,
+        method,
     };
 }
 export function extractTypeFromComment(commentValue, tag) {
@@ -190,6 +199,7 @@ export function cleanComment(commentValue) {
 export function cleanSpec(spec) {
     const propsToRemove = [
         "apiDir",
+        "routerType",
         "schemaDir",
         "docsUrl",
         "ui",

package/dist/lib/zod-converter.js

@@ -347,12 +347,8 @@ export class ZodSchemaConverter {
                                     }
                                     break;
                                 case "partial":
-                                    // All fields become optional
+                                    // All fields become optional (T | undefined), not nullable
                                     if (schema.properties) {
-                                        Object.keys(schema.properties).forEach((key) => {
-                                            schema.properties[key].nullable = true;
-                                        });
-                                        // Remove all required
                                         delete schema.required;
                                     }
                                     break;
@@ -390,14 +386,9 @@ export class ZodSchemaConverter {
                                     }
                                     break;
                                 case "required":
-                                    // All fields become required
+                                    // All fields become required — preserve genuine nullable flags
                                     if (schema.properties) {
-                                        const requiredFields = Object.keys(schema.properties);
-                                        schema.required = requiredFields;
-                                        // Remove nullable from fields
-                                        Object.keys(schema.properties).forEach((key) => {
-                                            delete schema.properties[key].nullable;
-                                        });
+                                        schema.required = Object.keys(schema.properties);
                                     }
                                     break;
                                 case "extend":
@@ -418,8 +409,9 @@ export class ZodSchemaConverter {
                                                     const propSchema = this.processZodNode(prop.value);
                                                     if (propSchema) {
                                                         extensionProperties[key] = propSchema;
-                                                        // Check if the schema itself has nullable set (which processZodNode sets for optional fields)
-                                                        const isOptional = propSchema.nullable === true;
+                                                        const isOptional = 
+                                                        // @ts-ignore
+                                                        this.isOptional(prop.value) || this.hasOptionalMethod(prop.value);
                                                         if (!isOptional) {
                                                             extensionRequired.push(key);
                                                         }
@@ -1239,20 +1231,17 @@ export class ZodSchemaConverter {
         // Apply the current method
         switch (methodName) {
             case "optional":
-                // Don't add nullable for schema references wrapped in allOf
-                // as it doesn't make sense in that context
-                if (!schema.allOf) {
-                    schema.nullable = true;
-                }
+                // optional means T | undefined — not in required array, no nullable flag
+                // Required array exclusion is handled by hasOptionalMethod() in processZodObject()
                 break;
             case "nullable":
-                // Don't add nullable for schema references wrapped in allOf
+                // nullable means T | null — field stays required but can be null
                 if (!schema.allOf) {
                     schema.nullable = true;
                 }
                 break;
-            case "nullish": // Handles both null and undefined
-                // Don't add nullable for schema references wrapped in allOf
+            case "nullish": // T | null | undefined
+                // Not in required array (handled by hasOptionalMethod) AND can be null
                 if (!schema.allOf) {
                     schema.nullable = true;
                 }
@@ -1540,7 +1529,6 @@ export class ZodSchemaConverter {
         if (t.isMemberExpression(node.callee) &&
             t.isIdentifier(node.callee.property) &&
             (node.callee.property.name === "optional" ||
-                node.callee.property.name === "nullable" ||
                 node.callee.property.name === "nullish")) {
             return true;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.9.4",
+  "version": "0.10.1",
   "description": "Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for Zod schemas and TypeScript types.",
   "type": "module",
   "main": "dist/index.js",