next-openapi-gen 0.9.1 → 0.9.3

package/README.md

@@ -213,7 +213,7 @@ export async function POST(request: NextRequest) {
 | `@description`         | Endpoint description                                                                                                     |
 | `@operationId`         | Custom operation ID (overrides auto-generated ID)                                                                        |
 | `@pathParams`          | Path parameters type/schema                                                                                              |
-| `@params`              | Query parameters type/schema                                                                                             |
+| `@params`              | Query parameters type/schema (use `@queryParams` if you have prettier-plugin-jsdoc conflicts)                           |
 | `@body`                | Request body type/schema                                                                                                 |
 | `@bodyDescription`     | Request body description                                                                                                 |
 | `@response`            | Response type/schema with optional code and description (`User`, `201:User`, `User:Description`, `201:User:Description`) |
@@ -671,6 +671,19 @@ export async function GET() {
 
 If no type/schema is provided for path parameters, a default schema will be generated.
 
+### Intelligent Examples
+
+The library generates intelligent examples for parameters based on their name:
+
+| Parameter name | Example                                  |
+| -------------- | ---------------------------------------- |
+| `id`, `*Id`    | `"123"` or `123`                         |
+| `slug`         | `"example-slug"`                         |
+| `uuid`         | `"123e4567-e89b-12d3-a456-426614174000"` |
+| `email`        | `"user@example.com"`                     |
+| `name`         | `"example-name"`                         |
+| `date`         | `"2023-01-01"`                           |
+
 ### TypeScript Generics Support
 
 The library supports TypeScript generic types and automatically resolves them during documentation generation:
@@ -718,18 +731,64 @@ export async function GET() {
 }
 ```
 
-### Intelligent Examples
+### TypeScript Utility Types Support
 
-The library generates intelligent examples for parameters based on their name:
+The library supports TypeScript utility types for extracting types from functions:
 
-| Parameter name | Example                                  |
-| -------------- | ---------------------------------------- |
-| `id`, `*Id`    | `"123"` or `123`                         |
-| `slug`         | `"example-slug"`                         |
-| `uuid`         | `"123e4567-e89b-12d3-a456-426614174000"` |
-| `email`        | `"user@example.com"`                     |
-| `name`         | `"example-name"`                         |
-| `date`         | `"2023-01-01"`                           |
+```typescript
+// src/app/api/products/route.utils.ts
+export async function getProductById(id: string): Promise<{
+  product: Product;
+  fetchedAt: string;
+}> {
+  // Implementation...
+}
+
+export function createProduct(
+  data: { name: string; price: number },
+  options: { notify: boolean }
+): { success: boolean; productId: string } {
+  // Implementation...
+}
+
+// src/types/product-types.ts
+
+// Extract return type from async functions
+export type ProductResponse = Awaited<ReturnType<typeof getProductById>>;
+
+// Extract return type from sync functions
+export type CreateResult = ReturnType<typeof createProduct>;
+
+// Extract parameter types as tuple
+export type CreateProductParams = Parameters<typeof createProduct>;
+
+// Extract specific parameter using indexed access
+export type ProductData = Parameters<typeof createProduct>[0];
+export type ProductOptions = Parameters<typeof createProduct>[1];
+
+// Use with generic types
+interface ApiResponse<T> {
+  success: boolean;
+  data: T;
+}
+
+export type ProductApiResponse = ApiResponse<ProductResponse>;
+
+/**
+ * @response ProductApiResponse
+ * @openapi
+ */
+export async function GET() {
+  // Fully typed response automatically documented
+}
+```
+
+**Supported utility types:**
+- `Awaited<T>` - Unwraps Promise types
+- `ReturnType<typeof func>` - Extracts function return type
+- `Parameters<typeof func>` - Extracts function parameters as tuple
+- `Parameters<typeof func>[N]` - Indexed access to specific parameter
+- Generic interfaces like `ApiResponse<T>` with type parameter substitution
 
 ## Advanced Zod Features
 

package/dist/lib/schema-processor.js

@@ -27,6 +27,9 @@ export class SchemaProcessor {
     zodSchemaConverter = null;
     schemaTypes;
     isResolvingPickOmitBase = false;
+    // Track imports per file for resolving ReturnType<typeof func>
+    importMap = {}; // { filePath: { importName: importPath } }
+    currentFilePath = ""; // Track the file being processed
     constructor(schemaDir, schemaType = "typescript", schemaFiles) {
         this.schemaDir = path.resolve(schemaDir);
         this.schemaTypes = normalizeSchemaTypes(schemaType);
@@ -90,7 +93,10 @@ export class SchemaProcessor {
         // Layer 1: TypeScript types (base layer)
         const filteredSchemas = {};
         Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
-            if (!this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key)) {
+            if (!this.isGenericTypeParameter(key) &&
+                !this.isInvalidSchemaName(key) &&
+                !this.isBuiltInUtilityType(key) &&
+                !this.isFunctionSchema(key)) {
                 filteredSchemas[key] = value;
             }
         });
@@ -105,7 +111,6 @@ export class SchemaProcessor {
         return merged;
     }
     findSchemaDefinition(schemaName, contentType) {
-        let schemaNode = null;
         // Assign type that is actually processed
         this.contentType = contentType;
         // Check if the schemaName is a generic type (contains < and >)
@@ -136,7 +141,7 @@ export class SchemaProcessor {
         }
         // Fall back to TypeScript types
         this.scanSchemaDir(this.schemaDir, schemaName);
-        return schemaNode;
+        return this.openapiDefinitions[schemaName] || {};
     }
     scanSchemaDir(dir, schemaName) {
         let files = this.directoryCache[dir];
@@ -159,40 +164,160 @@ export class SchemaProcessor {
             }
         });
     }
-    collectTypeDefinitions(ast, schemaName) {
+    collectImports(ast, filePath) {
+        // Normalize path to avoid Windows/Unix path separator issues
+        const normalizedPath = path.normalize(filePath);
+        if (!this.importMap[normalizedPath]) {
+            this.importMap[normalizedPath] = {};
+        }
+        traverse(ast, {
+            ImportDeclaration: (path) => {
+                const importPath = path.node.source.value;
+                // Handle named imports: import { foo, bar } from './file'
+                path.node.specifiers.forEach((specifier) => {
+                    if (t.isImportSpecifier(specifier)) {
+                        const importedName = t.isIdentifier(specifier.imported) ? specifier.imported.name : specifier.imported.value;
+                        this.importMap[normalizedPath][importedName] = importPath;
+                    }
+                    // Handle default imports: import foo from './file'
+                    else if (t.isImportDefaultSpecifier(specifier)) {
+                        const importedName = specifier.local.name;
+                        this.importMap[normalizedPath][importedName] = importPath;
+                    }
+                    // Handle namespace imports: import * as foo from './file'
+                    else if (t.isImportNamespaceSpecifier(specifier)) {
+                        const importedName = specifier.local.name;
+                        this.importMap[normalizedPath][importedName] = importPath;
+                    }
+                });
+            },
+        });
+    }
+    /**
+     * Resolve an import path relative to the current file
+     * Converts import paths like "../app/api/products/route.utils" to absolute file paths
+     */
+    resolveImportPath(importPath, fromFilePath) {
+        // Skip node_modules imports
+        if (!importPath.startsWith('.')) {
+            return null;
+        }
+        const fromDir = path.dirname(fromFilePath);
+        let resolvedPath = path.resolve(fromDir, importPath);
+        // Try with .ts extension
+        if (fs.existsSync(resolvedPath + '.ts')) {
+            return resolvedPath + '.ts';
+        }
+        // Try with .tsx extension
+        if (fs.existsSync(resolvedPath + '.tsx')) {
+            return resolvedPath + '.tsx';
+        }
+        // Try as-is (might already have extension)
+        if (fs.existsSync(resolvedPath)) {
+            return resolvedPath;
+        }
+        return null;
+    }
+    /**
+     * Collect all exported type definitions from an AST without filtering by name
+     * Used when processing imported files to ensure all referenced types are available
+     */
+    collectAllExportedDefinitions(ast, filePath) {
+        const currentFile = filePath || this.currentFilePath;
+        traverse(ast, {
+            TSTypeAliasDeclaration: (path) => {
+                if (path.node.id && t.isIdentifier(path.node.id)) {
+                    const name = path.node.id.name;
+                    if (!this.typeDefinitions[name]) {
+                        const node = (path.node.typeParameters && path.node.typeParameters.params.length > 0)
+                            ? path.node
+                            : path.node.typeAnnotation;
+                        this.typeDefinitions[name] = { node, filePath: currentFile };
+                    }
+                }
+            },
+            TSInterfaceDeclaration: (path) => {
+                if (path.node.id && t.isIdentifier(path.node.id)) {
+                    const name = path.node.id.name;
+                    if (!this.typeDefinitions[name]) {
+                        this.typeDefinitions[name] = { node: path.node, filePath: currentFile };
+                    }
+                }
+            },
+            TSEnumDeclaration: (path) => {
+                if (path.node.id && t.isIdentifier(path.node.id)) {
+                    const name = path.node.id.name;
+                    if (!this.typeDefinitions[name]) {
+                        this.typeDefinitions[name] = { node: path.node, filePath: currentFile };
+                    }
+                }
+            },
+            ExportNamedDeclaration: (path) => {
+                // Handle exported interfaces
+                if (t.isTSInterfaceDeclaration(path.node.declaration)) {
+                    const interfaceDecl = path.node.declaration;
+                    if (interfaceDecl.id && t.isIdentifier(interfaceDecl.id)) {
+                        const name = interfaceDecl.id.name;
+                        if (!this.typeDefinitions[name]) {
+                            this.typeDefinitions[name] = { node: interfaceDecl, filePath: currentFile };
+                        }
+                    }
+                }
+                // Handle exported type aliases
+                if (t.isTSTypeAliasDeclaration(path.node.declaration)) {
+                    const typeDecl = path.node.declaration;
+                    if (typeDecl.id && t.isIdentifier(typeDecl.id)) {
+                        const name = typeDecl.id.name;
+                        if (!this.typeDefinitions[name]) {
+                            const node = (typeDecl.typeParameters && typeDecl.typeParameters.params.length > 0)
+                                ? typeDecl
+                                : typeDecl.typeAnnotation;
+                            this.typeDefinitions[name] = { node, filePath: currentFile };
+                        }
+                    }
+                }
+            },
+        });
+    }
+    collectTypeDefinitions(ast, schemaName, filePath) {
+        const currentFile = filePath || this.currentFilePath;
         traverse(ast, {
             VariableDeclarator: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
                     const name = path.node.id.name;
-                    this.typeDefinitions[name] = path.node.init || path.node;
+                    this.typeDefinitions[name] = { node: path.node.init || path.node, filePath: currentFile };
                 }
             },
             TSTypeAliasDeclaration: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
                     const name = path.node.id.name;
                     // Store the full node for generic types, just the type annotation for regular types
-                    if (path.node.typeParameters &&
-                        path.node.typeParameters.params.length > 0) {
-                        this.typeDefinitions[name] = path.node; // Store the full declaration for generic types
-                    }
-                    else {
-                        this.typeDefinitions[name] = path.node.typeAnnotation; // Store just the type annotation for regular types
-                    }
+                    const node = (path.node.typeParameters && path.node.typeParameters.params.length > 0)
+                        ? path.node // Store the full declaration for generic types
+                        : path.node.typeAnnotation; // Store just the type annotation for regular types
+                    this.typeDefinitions[name] = { node, filePath: currentFile };
                 }
             },
             TSInterfaceDeclaration: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
                     const name = path.node.id.name;
-                    this.typeDefinitions[name] = path.node;
+                    this.typeDefinitions[name] = { node: path.node, filePath: currentFile };
                 }
             },
             TSEnumDeclaration: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
                     const name = path.node.id.name;
-                    this.typeDefinitions[name] = path.node;
+                    this.typeDefinitions[name] = { node: path.node, filePath: currentFile };
                 }
             },
-            // Collect exported zod schemas
+            // Collect function declarations for ReturnType<typeof func> support
+            FunctionDeclaration: (path) => {
+                if (path.node.id && t.isIdentifier(path.node.id, { name: schemaName })) {
+                    const name = path.node.id.name;
+                    this.typeDefinitions[name] = { node: path.node, filePath: currentFile };
+                }
+            },
+            // Collect exported zod schemas and functions
             ExportNamedDeclaration: (path) => {
                 if (t.isVariableDeclaration(path.node.declaration)) {
                     path.node.declaration.declarations.forEach((declaration) => {
@@ -205,11 +330,19 @@ export class SchemaProcessor {
                                 t.isIdentifier(declaration.init.callee.object) &&
                                 declaration.init.callee.object.name === "z") {
                                 const name = declaration.id.name;
-                                this.typeDefinitions[name] = declaration.init;
+                                this.typeDefinitions[name] = { node: declaration.init, filePath: currentFile };
                             }
                         }
                     });
                 }
+                // Handle exported function declarations
+                if (t.isFunctionDeclaration(path.node.declaration)) {
+                    const funcDecl = path.node.declaration;
+                    if (funcDecl.id && t.isIdentifier(funcDecl.id, { name: schemaName })) {
+                        const name = funcDecl.id.name;
+                        this.typeDefinitions[name] = { node: funcDecl, filePath: currentFile };
+                    }
+                }
             },
         });
     }
@@ -230,9 +363,10 @@ export class SchemaProcessor {
                     return zodSchema;
                 }
             }
-            const typeNode = this.typeDefinitions[typeName.toString()];
-            if (!typeNode)
+            const typeDefEntry = this.typeDefinitions[typeName.toString()];
+            if (!typeDefEntry)
                 return {};
+            const typeNode = typeDefEntry.node || typeDefEntry; // Support both old and new format
             // Handle generic type alias declarations (full node)
             if (t.isTSTypeAliasDeclaration(typeNode)) {
                 // This is a generic type, should be handled by the caller via resolveGenericType
@@ -303,6 +437,10 @@ export class SchemaProcessor {
             if (t.isTSTypeReference(typeNode)) {
                 return this.resolveTSNodeType(typeNode);
             }
+            // Handle indexed access types (e.g., Parameters<typeof func>[0])
+            if (t.isTSIndexedAccessType(typeNode)) {
+                return this.resolveTSNodeType(typeNode);
+            }
             return {};
         }
         finally {
@@ -373,12 +511,53 @@ export class SchemaProcessor {
                 return this.resolveTSNodeType(syntheticNode);
             }
         }
+        // Handle indexed access types: SomeType[0] or SomeType["key"]
+        if (t.isTSIndexedAccessType(node)) {
+            const objectType = this.resolveTSNodeType(node.objectType);
+            const indexType = node.indexType;
+            // Handle numeric index: Parameters<typeof func>[0]
+            if (t.isTSLiteralType(indexType) && t.isNumericLiteral(indexType.literal)) {
+                const index = indexType.literal.value;
+                // If objectType is a tuple (has prefixItems), get the specific item
+                if (objectType.prefixItems && Array.isArray(objectType.prefixItems)) {
+                    if (index < objectType.prefixItems.length) {
+                        return objectType.prefixItems[index];
+                    }
+                    else {
+                        logger.warn(`Index ${index} is out of bounds for tuple type.`);
+                        return { type: "object" };
+                    }
+                }
+                // If objectType is a regular array, return the items type
+                if (objectType.type === "array" && objectType.items) {
+                    return objectType.items;
+                }
+            }
+            // Handle string index: SomeType["propertyName"]
+            if (t.isTSLiteralType(indexType) && t.isStringLiteral(indexType.literal)) {
+                const key = indexType.literal.value;
+                // If objectType has properties, get the specific property
+                if (objectType.properties && objectType.properties[key]) {
+                    return objectType.properties[key];
+                }
+            }
+            // Fallback
+            return { type: "object" };
+        }
         if (t.isTSTypeReference(node) && t.isIdentifier(node.typeName)) {
             const typeName = node.typeName.name;
             // Special handling for built-in types
             if (typeName === "Date") {
                 return { type: "string", format: "date-time" };
             }
+            // Handle Promise<T> - in OpenAPI, promises are transparent (we document the resolved value)
+            if (typeName === "Promise") {
+                if (node.typeParameters && node.typeParameters.params.length > 0) {
+                    // Return the inner type directly - promises are async wrappers
+                    return this.resolveTSNodeType(node.typeParameters.params[0]);
+                }
+                return { type: "object" }; // Promise with no type parameter
+            }
             if (typeName === "Array" || typeName === "ReadonlyArray") {
                 if (node.typeParameters && node.typeParameters.params.length > 0) {
                     return {
@@ -406,6 +585,160 @@ export class SchemaProcessor {
                     return this.resolveTSNodeType(node.typeParameters.params[0]);
                 }
             }
+            // Handle Awaited<T> utility type
+            if (typeName === "Awaited") {
+                if (node.typeParameters && node.typeParameters.params.length > 0) {
+                    // Unwrap the inner type - promises are transparent in OpenAPI
+                    return this.resolveTSNodeType(node.typeParameters.params[0]);
+                }
+            }
+            // Handle ReturnType<typeof X> utility type
+            if (typeName === "ReturnType") {
+                if (node.typeParameters && node.typeParameters.params.length > 0) {
+                    const typeParam = node.typeParameters.params[0];
+                    // ReturnType<typeof functionName>
+                    if (t.isTSTypeQuery(typeParam)) {
+                        const funcName = t.isIdentifier(typeParam.exprName)
+                            ? typeParam.exprName.name
+                            : null;
+                        if (funcName) {
+                            // Save current file path before findSchemaDefinition which may change it
+                            const savedFilePath = this.currentFilePath;
+                            // First try to find the function in the current file
+                            this.findSchemaDefinition(funcName, this.contentType);
+                            let funcDefEntry = this.typeDefinitions[funcName];
+                            let funcNode = funcDefEntry?.node || funcDefEntry; // Support both old and new format
+                            const funcFilePath = funcDefEntry?.filePath;
+                            // If not found, check if it's an imported function
+                            // Use the saved file path (where the utility type is defined)
+                            const sourceFilePath = savedFilePath;
+                            const normalizedSourcePath = path.normalize(sourceFilePath);
+                            if (!funcNode && sourceFilePath && this.importMap[normalizedSourcePath]) {
+                                const importPath = this.importMap[normalizedSourcePath][funcName];
+                                if (importPath) {
+                                    // Resolve the import path to an absolute file path
+                                    const resolvedPath = this.resolveImportPath(importPath, sourceFilePath);
+                                    if (resolvedPath) {
+                                        // Process the imported file to collect the function
+                                        const content = fs.readFileSync(resolvedPath, "utf-8");
+                                        const ast = parseTypeScriptFile(content);
+                                        // Collect imports and type definitions from the imported file
+                                        this.collectImports(ast, resolvedPath);
+                                        this.collectTypeDefinitions(ast, funcName, resolvedPath);
+                                        // Also collect all exported types/interfaces from the same file
+                                        // This ensures referenced types like Product are available
+                                        this.collectAllExportedDefinitions(ast, resolvedPath);
+                                        // Now try to get the function node again
+                                        funcDefEntry = this.typeDefinitions[funcName];
+                                        funcNode = funcDefEntry?.node || funcDefEntry;
+                                    }
+                                }
+                            }
+                            if (funcNode) {
+                                // Extract the return type annotation
+                                const returnTypeNode = this.extractFunctionReturnType(funcNode);
+                                if (returnTypeNode) {
+                                    // Recursively resolve the return type
+                                    return this.resolveTSNodeType(returnTypeNode);
+                                }
+                                else {
+                                    logger.warn(`ReturnType<typeof ${funcName}>: Function '${funcName}' does not have an explicit return type annotation. ` +
+                                        `Add a return type to the function signature for accurate schema generation.`);
+                                    return { type: "object" };
+                                }
+                            }
+                            else {
+                                logger.warn(`ReturnType<typeof ${funcName}>: Function '${funcName}' not found in schema files or imports. ` +
+                                    `Ensure the function is exported and imported correctly.`);
+                                return { type: "object" };
+                            }
+                        }
+                    }
+                    // Fallback: If not TSTypeQuery, try resolving directly
+                    logger.warn(`ReturnType<T>: Expected 'typeof functionName' but got a different type. ` +
+                        `Use ReturnType<typeof yourFunction> pattern for best results.`);
+                    return this.resolveTSNodeType(typeParam);
+                }
+            }
+            // Handle Parameters<typeof X> utility type
+            if (typeName === "Parameters") {
+                if (node.typeParameters && node.typeParameters.params.length > 0) {
+                    const typeParam = node.typeParameters.params[0];
+                    // Parameters<typeof functionName>
+                    if (t.isTSTypeQuery(typeParam)) {
+                        const funcName = t.isIdentifier(typeParam.exprName)
+                            ? typeParam.exprName.name
+                            : null;
+                        if (funcName) {
+                            // Save current file path before findSchemaDefinition which may change it
+                            const savedFilePath = this.currentFilePath;
+                            // First try to find the function in the current file
+                            this.findSchemaDefinition(funcName, this.contentType);
+                            let funcDefEntry = this.typeDefinitions[funcName];
+                            let funcNode = funcDefEntry?.node || funcDefEntry; // Support both old and new format
+                            const funcFilePath = funcDefEntry?.filePath;
+                            // If not found, check if it's an imported function
+                            // Use the saved file path (where the utility type is defined)
+                            const sourceFilePath = savedFilePath;
+                            const normalizedSourcePath = path.normalize(sourceFilePath);
+                            if (!funcNode && sourceFilePath && this.importMap[normalizedSourcePath]) {
+                                const importPath = this.importMap[normalizedSourcePath][funcName];
+                                if (importPath) {
+                                    // Resolve the import path to an absolute file path
+                                    const resolvedPath = this.resolveImportPath(importPath, sourceFilePath);
+                                    if (resolvedPath) {
+                                        // Process the imported file to collect the function
+                                        const content = fs.readFileSync(resolvedPath, "utf-8");
+                                        const ast = parseTypeScriptFile(content);
+                                        // Collect imports and type definitions from the imported file
+                                        this.collectImports(ast, resolvedPath);
+                                        this.collectTypeDefinitions(ast, funcName, resolvedPath);
+                                        // Also collect all exported types/interfaces from the same file
+                                        // This ensures referenced types like Product are available
+                                        this.collectAllExportedDefinitions(ast, resolvedPath);
+                                        // Now try to get the function node again
+                                        funcDefEntry = this.typeDefinitions[funcName];
+                                        funcNode = funcDefEntry?.node || funcDefEntry;
+                                    }
+                                }
+                            }
+                            if (funcNode) {
+                                // Extract parameters from function
+                                const params = this.extractFunctionParameters(funcNode);
+                                if (params && params.length > 0) {
+                                    // Parameters<T> returns a tuple type [Param1, Param2, ...]
+                                    const paramTypes = params.map((param) => {
+                                        if (param.typeAnnotation &&
+                                            param.typeAnnotation.typeAnnotation) {
+                                            return this.resolveTSNodeType(param.typeAnnotation.typeAnnotation);
+                                        }
+                                        return { type: "any" };
+                                    });
+                                    // Return as tuple (array with prefixItems for OpenAPI 3.1)
+                                    return {
+                                        type: "array",
+                                        prefixItems: paramTypes,
+                                        items: false,
+                                        minItems: paramTypes.length,
+                                        maxItems: paramTypes.length,
+                                    };
+                                }
+                                else {
+                                    // No parameters
+                                    return {
+                                        type: "array",
+                                        maxItems: 0,
+                                    };
+                                }
+                            }
+                            else {
+                                logger.warn(`Parameters<typeof ${funcName}>: Function '${funcName}' not found in schema files or imports.`);
+                                return { type: "array", items: { type: "object" } };
+                            }
+                        }
+                    }
+                }
+            }
             if (typeName === "Pick" || typeName === "Omit") {
                 if (node.typeParameters && node.typeParameters.params.length > 1) {
                     const baseTypeParam = node.typeParameters.params[0];
@@ -444,7 +777,8 @@ export class SchemaProcessor {
             if (node.typeParameters && node.typeParameters.params.length > 0) {
                 // Find the generic type definition first
                 this.findSchemaDefinition(typeName, this.contentType);
-                const genericTypeDefinition = this.typeDefinitions[typeName];
+                const genericDefEntry = this.typeDefinitions[typeName];
+                const genericTypeDefinition = genericDefEntry?.node || genericDefEntry;
                 if (genericTypeDefinition) {
                     // Resolve the generic type by substituting type parameters
                     return this.resolveGenericType(genericTypeDefinition, node.typeParameters.params, typeName);
@@ -568,7 +902,12 @@ export class SchemaProcessor {
             // Recognizes different elements of TS like variable, type, interface, enum
             const content = fs.readFileSync(filePath, "utf-8");
             const ast = parseTypeScriptFile(content);
-            this.collectTypeDefinitions(ast, schemaName);
+            // Track current file path for import resolution (normalize for consistency)
+            this.currentFilePath = path.normalize(filePath);
+            // Collect imports from this file
+            this.collectImports(ast, filePath);
+            // Collect type definitions, passing the file path explicitly
+            this.collectTypeDefinitions(ast, schemaName, filePath);
             // Reset the set of processed types before each schema processing
             this.processingTypes.clear();
             const definition = this.resolveType(schemaName);
@@ -838,28 +1177,24 @@ export class SchemaProcessor {
         // Strip array notation for schema lookups
         const baseBodyType = stripArrayNotation(bodyType);
         const baseResponseType = stripArrayNotation(responseType);
-        let params = paramsType ? this.openapiDefinitions[paramsType] : {};
-        let pathParams = pathParamsType
-            ? this.openapiDefinitions[pathParamsType]
-            : {};
-        let body = baseBodyType ? this.openapiDefinitions[baseBodyType] : {};
-        let responses = baseResponseType ? this.openapiDefinitions[baseResponseType] : {};
-        if (paramsType && !params) {
+        // Check if schemas exist, if not try to find them
+        if (paramsType && !this.openapiDefinitions[paramsType]) {
             this.findSchemaDefinition(paramsType, "params");
-            params = this.openapiDefinitions[paramsType] || {};
         }
-        if (pathParamsType && !pathParams) {
+        if (pathParamsType && !this.openapiDefinitions[pathParamsType]) {
             this.findSchemaDefinition(pathParamsType, "pathParams");
-            pathParams = this.openapiDefinitions[pathParamsType] || {};
         }
-        if (baseBodyType && !body) {
+        if (baseBodyType && !this.openapiDefinitions[baseBodyType]) {
             this.findSchemaDefinition(baseBodyType, "body");
-            body = this.openapiDefinitions[baseBodyType] || {};
         }
-        if (baseResponseType && !responses) {
+        if (baseResponseType && !this.openapiDefinitions[baseResponseType]) {
             this.findSchemaDefinition(baseResponseType, "response");
-            responses = this.openapiDefinitions[baseResponseType] || {};
         }
+        // Now get the schemas (will be {} if still not found)
+        let params = paramsType ? this.openapiDefinitions[paramsType] || {} : {};
+        let pathParams = pathParamsType ? this.openapiDefinitions[pathParamsType] || {} : {};
+        let body = baseBodyType ? this.openapiDefinitions[baseBodyType] || {} : {};
+        let responses = baseResponseType ? this.openapiDefinitions[baseResponseType] || {} : {};
         if (this.schemaTypes.includes("zod")) {
             const schemasToProcess = [
                 paramsType,
@@ -895,7 +1230,8 @@ export class SchemaProcessor {
         const { baseTypeName, typeArguments } = parsed;
         // Find the base generic type definition
         this.scanSchemaDir(this.schemaDir, baseTypeName);
-        const genericTypeDefinition = this.typeDefinitions[baseTypeName];
+        const genericDefEntry = this.typeDefinitions[baseTypeName];
+        const genericTypeDefinition = genericDefEntry?.node || genericDefEntry;
         if (!genericTypeDefinition) {
             logger.debug(`Generic type definition not found for: ${baseTypeName}`);
             return {};
@@ -936,6 +1272,34 @@ export class SchemaProcessor {
         // Schema names should not contain { } : ? spaces or other special characters
         return /[{}\s:?]/.test(schemaName);
     }
+    /**
+     * Check if a type name is a built-in TypeScript utility type
+     * @param {string} typeName - The type name to check
+     * @returns {boolean} - True if it's a built-in utility type
+     */
+    isBuiltInUtilityType(typeName) {
+        const builtInTypes = [
+            'Awaited', 'Partial', 'Required', 'Readonly', 'Record', 'Pick', 'Omit',
+            'Exclude', 'Extract', 'NonNullable', 'Parameters', 'ConstructorParameters',
+            'ReturnType', 'InstanceType', 'ThisParameterType', 'OmitThisParameter',
+            'ThisType', 'Uppercase', 'Lowercase', 'Capitalize', 'Uncapitalize',
+            'Promise', 'Array', 'ReadonlyArray', 'Map', 'Set', 'WeakMap', 'WeakSet'
+        ];
+        return builtInTypes.includes(typeName);
+    }
+    /**
+     * Check if a schema name is a function (should not be included in schemas)
+     * Functions are identified by having a node that is a function declaration
+     */
+    isFunctionSchema(schemaName) {
+        const entry = this.typeDefinitions[schemaName];
+        if (!entry)
+            return false;
+        const node = entry.node || entry;
+        return t.isFunctionDeclaration(node) ||
+            t.isFunctionExpression(node) ||
+            t.isArrowFunctionExpression(node);
+    }
     /**
      * Parse a generic type string into base type and arguments
      * @param genericTypeString - The string like "MyApiSuccessResponseBody<LLMSResponse>"
@@ -1032,6 +1396,8 @@ export class SchemaProcessor {
     resolveGenericType(genericTypeDefinition, typeArguments, typeName) {
         // Extract type parameters from the generic type definition
         let typeParameters = [];
+        let bodyToResolve = null;
+        // Handle type alias declarations
         if (t.isTSTypeAliasDeclaration(genericTypeDefinition)) {
             if (genericTypeDefinition.typeParameters &&
                 genericTypeDefinition.typeParameters.params) {
@@ -1044,18 +1410,35 @@ export class SchemaProcessor {
                         : param.name?.name || param;
                 });
             }
-            // Create a mapping from type parameters to actual types
-            const typeParameterMap = {};
-            typeParameters.forEach((param, index) => {
-                if (index < typeArguments.length) {
-                    typeParameterMap[param] = typeArguments[index];
-                }
-            });
-            // Resolve the type annotation with substituted type parameters
-            return this.resolveTypeWithSubstitution(genericTypeDefinition.typeAnnotation, typeParameterMap);
+            bodyToResolve = genericTypeDefinition.typeAnnotation;
         }
-        // If we can't process the generic type, return empty object
-        return {};
+        // Handle interface declarations
+        if (t.isTSInterfaceDeclaration(genericTypeDefinition)) {
+            if (genericTypeDefinition.typeParameters &&
+                genericTypeDefinition.typeParameters.params) {
+                typeParameters = genericTypeDefinition.typeParameters.params.map((param) => {
+                    if (t.isTSTypeParameter(param)) {
+                        return param.name;
+                    }
+                    return t.isIdentifier(param)
+                        ? param.name
+                        : param.name?.name || param;
+                });
+            }
+            bodyToResolve = genericTypeDefinition.body;
+        }
+        if (!bodyToResolve) {
+            return {};
+        }
+        // Create a mapping from type parameters to actual types
+        const typeParameterMap = {};
+        typeParameters.forEach((param, index) => {
+            if (index < typeArguments.length) {
+                typeParameterMap[param] = typeArguments[index];
+            }
+        });
+        // Resolve the type annotation with substituted type parameters
+        return this.resolveTypeWithSubstitution(bodyToResolve, typeParameterMap);
     }
     /**
      * Resolve a type node with type parameter substitution
@@ -1149,7 +1532,66 @@ export class SchemaProcessor {
             });
             return { type: "object", properties };
         }
+        // Handle interface body (from generic interfaces)
+        if (t.isTSInterfaceBody(node)) {
+            const properties = {};
+            node.body.forEach((member) => {
+                if (t.isTSPropertySignature(member) && t.isIdentifier(member.key)) {
+                    const propName = member.key.name;
+                    properties[propName] = this.resolveTypeWithSubstitution(member.typeAnnotation?.typeAnnotation, typeParameterMap);
+                }
+            });
+            return { type: "object", properties };
+        }
         // Fallback to standard type resolution
         return this.resolveTSNodeType(node);
     }
+    /**
+     * Extracts the return type annotation from a function AST node
+     * @param funcNode - Function declaration or arrow function AST node
+     * @returns The return type annotation node, or null if not found
+     */
+    extractFunctionReturnType(funcNode) {
+        // Handle FunctionDeclaration: function foo(): ReturnType {}
+        if (t.isFunctionDeclaration(funcNode) || t.isFunctionExpression(funcNode)) {
+            return funcNode.returnType && t.isTSTypeAnnotation(funcNode.returnType)
+                ? funcNode.returnType.typeAnnotation
+                : null;
+        }
+        // Handle ArrowFunctionExpression: const foo = (): ReturnType => {}
+        if (t.isArrowFunctionExpression(funcNode)) {
+            return funcNode.returnType && t.isTSTypeAnnotation(funcNode.returnType)
+                ? funcNode.returnType.typeAnnotation
+                : null;
+        }
+        // Handle VariableDeclarator with arrow function
+        if (t.isVariableDeclarator(funcNode) &&
+            t.isArrowFunctionExpression(funcNode.init)) {
+            return funcNode.init.returnType && t.isTSTypeAnnotation(funcNode.init.returnType)
+                ? funcNode.init.returnType.typeAnnotation
+                : null;
+        }
+        return null;
+    }
+    /**
+     * Extracts parameter nodes from a function AST node
+     * @param funcNode - Function declaration or arrow function AST node
+     * @returns Array of parameter nodes
+     */
+    extractFunctionParameters(funcNode) {
+        // Handle FunctionDeclaration
+        if (t.isFunctionDeclaration(funcNode) || t.isFunctionExpression(funcNode)) {
+            return funcNode.params || [];
+        }
+        // Handle ArrowFunctionExpression
+        if (t.isArrowFunctionExpression(funcNode)) {
+            return funcNode.params || [];
+        }
+        // Handle VariableDeclarator with arrow function
+        if (t.isVariableDeclarator(funcNode) &&
+            t.isArrowFunctionExpression(funcNode.init)) {
+            return funcNode.init.params || [];
+        }
+        return [];
+    }
 }

package/dist/lib/utils.js

@@ -85,8 +85,9 @@ export function extractJSDocComments(path) {
                     tag = match[1].trim();
                 }
             }
-            if (commentValue.includes("@params")) {
-                paramsType = extractTypeFromComment(commentValue, "@params");
+            if (commentValue.includes("@params") || commentValue.includes("@queryParams")) {
+                paramsType = extractTypeFromComment(commentValue, "@queryParams") ||
+                    extractTypeFromComment(commentValue, "@params");
             }
             if (commentValue.includes("@pathParams")) {
                 pathParamsType = extractTypeFromComment(commentValue, "@pathParams");
@@ -169,8 +170,9 @@ export function extractJSDocComments(path) {
 }
 export function extractTypeFromComment(commentValue, tag) {
     // Updated regex to support generic types with angle brackets and array brackets
+    // Use multiline mode (m flag) to match tag at start of line (after optional * from JSDoc)
     return (commentValue
-        .match(new RegExp(`${tag}\\s*\\s*([\\w<>,\\s\\[\\]]+)`))?.[1]
+        .match(new RegExp(`^\\s*\\*?\\s*${tag}\\s+([\\w<>,\\s\\[\\]]+)`, 'm'))?.[1]
         ?.trim() || "");
 }
 export function cleanComment(commentValue) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "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",