next-openapi-gen 0.7.8 → 0.7.10

package/README.md

@@ -63,25 +63,27 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
   "outputDir": "./public",
   "docsUrl": "/api-docs",
   "includeOpenApiRoutes": false,
+  "ignoreRoutes": [],
   "debug": false
 }
 ```
 
 ### Configuration Options
 
-| Option                 | Description                                                            |
-| ---------------------- | ---------------------------------------------------------------------- |
-| `apiDir`               | Path to the API directory                                              |
-| `schemaDir`            | Path to the types/schemas directory                                    |
-| `schemaType`           | Schema type: `"zod"` or `"typescript"`                                 |
-| `outputFile`           | Name of the OpenAPI output file                                        |
-| `outputDir`            | Directory where OpenAPI file will be generated (default: `"./public"`) |
-| `docsUrl`              | API documentation URL (for Swagger UI)                                 |
-| `includeOpenApiRoutes` | Whether to include only routes with @openapi tag                       |
-| `defaultResponseSet`   | Default error response set for all endpoints                           |
-| `responseSets`         | Named sets of error response codes                                     |
-| `errorConfig`          | Error schema configuration                                             |
-| `debug`                | Enable detailed logging during generation                              |
+| Option                 | Description                                                                |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `apiDir`               | Path to the API directory                                                  |
+| `schemaDir`            | Path to the types/schemas directory                                        |
+| `schemaType`           | Schema type: `"zod"` or `"typescript"`                                     |
+| `outputFile`           | Name of the OpenAPI output file                                            |
+| `outputDir`            | Directory where OpenAPI file will be generated (default: `"./public"`)     |
+| `docsUrl`              | API documentation URL (for Swagger UI)                                     |
+| `includeOpenApiRoutes` | Whether to include only routes with @openapi tag                           |
+| `ignoreRoutes`         | Array of route patterns to exclude from documentation (supports wildcards) |
+| `defaultResponseSet`   | Default error response set for all endpoints                               |
+| `responseSets`         | Named sets of error response codes                                         |
+| `errorConfig`          | Error schema configuration                                                 |
+| `debug`                | Enable detailed logging during generation                                  |
 
 ## Documenting Your API
 
@@ -168,6 +170,7 @@ export async function GET(
 | `@tag`                 | Custom tag                                                                                                               |
 | `@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                                                                            |
 
 ## CLI Usage
 
@@ -537,6 +540,48 @@ export async function PUT() {}
 }
 ```
 
+## Ignoring Routes
+
+You can exclude routes from OpenAPI documentation in two ways:
+
+### Using @ignore Tag
+
+Add the `@ignore` tag to any route you want to exclude:
+
+```typescript
+// src/app/api/internal/route.ts
+
+/**
+ * Internal route - not for documentation
+ * @ignore
+ */
+export async function GET() {
+  // This route will not appear in OpenAPI documentation
+}
+```
+
+### Using ignoreRoutes Configuration
+
+Add patterns to your `next.openapi.json` configuration file to exclude multiple routes at once:
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Next.js API",
+    "version": "1.0.0"
+  },
+  "apiDir": "src/app/api",
+  "ignoreRoutes": ["/internal/*", "/debug", "/admin/test/*"]
+}
+```
+
+Pattern matching supports wildcards:
+
+- `/internal/*` - Ignores all routes under `/internal/`
+- `/debug` - Ignores only the `/debug` route
+- `/admin/*/temp` - Ignores routes like `/admin/users/temp`, `/admin/posts/temp`
+
 ## Advanced Usage
 
 ### Automatic Path Parameter Detection
@@ -554,6 +599,53 @@ export async function GET() {
 
 If no type/schema is provided for path parameters, a default schema will be generated.
 
+### TypeScript Generics Support
+
+The library supports TypeScript generic types and automatically resolves them during documentation generation:
+
+```typescript
+// src/app/api/llms/route.ts
+
+import { NextResponse } from "next/server";
+
+// Define generic response wrapper
+type MyApiSuccessResponseBody<T> = T & {
+  success: true;
+  httpCode: string;
+};
+
+// Define specific response data
+type LLMSResponse = {
+  llms: Array<{
+    id: string;
+    name: string;
+    provider: string;
+    isDefault: boolean;
+  }>;
+};
+
+/**
+ * Get list of available LLMs
+ * @description Get list of available LLMs with success wrapper
+ * @response 200:MyApiSuccessResponseBody<LLMSResponse>
+ * @openapi
+ */
+export async function GET() {
+  return NextResponse.json({
+    success: true,
+    httpCode: "200",
+    llms: [
+      {
+        id: "gpt-5",
+        name: "GPT-5",
+        provider: "OpenAI",
+        isDefault: true,
+      },
+    ],
+  });
+}
+```
+
 ### Intelligent Examples
 
 The library generates intelligent examples for parameters based on their name:

package/dist/lib/openapi-generator.js

@@ -17,7 +17,7 @@ export class OpenApiGenerator {
     }
     getConfig() {
         // @ts-ignore
-        const { apiDir, schemaDir, docsUrl, ui, outputFile, outputDir, includeOpenApiRoutes, schemaType = "typescript", defaultResponseSet, responseSets, errorConfig, debug } = this.template;
+        const { apiDir, schemaDir, docsUrl, ui, outputFile, outputDir, includeOpenApiRoutes, ignoreRoutes, schemaType = "typescript", defaultResponseSet, responseSets, errorConfig, debug } = this.template;
         return {
             apiDir: apiDir || "./src/app/api",
             schemaDir: schemaDir || "./src",
@@ -26,6 +26,7 @@ export class OpenApiGenerator {
             outputFile: outputFile || "openapi.json",
             outputDir: outputDir || "./public",
             includeOpenApiRoutes: includeOpenApiRoutes || false,
+            ignoreRoutes: ignoreRoutes || [],
             schemaType,
             defaultResponseSet,
             responseSets,

package/dist/lib/route-processor.js

@@ -1,7 +1,9 @@
 import * as t from "@babel/types";
 import fs from "fs";
 import path from "path";
-import traverse from "@babel/traverse";
+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 { logger } from "./logger.js";
@@ -23,14 +25,15 @@ export class RouteProcessor {
         // 1. Add success response
         const successCode = dataTypes.successCode || this.getDefaultSuccessCode(method);
         if (dataTypes.responseType) {
-            const responseSchema = this.schemaProcessor.getSchemaContent({
+            // Ensure the schema is defined in components/schemas
+            this.schemaProcessor.getSchemaContent({
                 responseType: dataTypes.responseType,
-            }).responses;
+            });
             responses[successCode] = {
                 description: dataTypes.responseDescription || "Successful response",
                 content: {
                     "application/json": {
-                        schema: responseSchema,
+                        schema: { $ref: `#/components/schemas/${dataTypes.responseType}` },
                     },
                 },
             };
@@ -112,24 +115,49 @@ export class RouteProcessor {
     isRoute(varName) {
         return HTTP_METHODS.includes(varName);
     }
+    /**
+     * Check if a route should be ignored based on config patterns or @ignore tag
+     */
+    shouldIgnoreRoute(routePath, dataTypes) {
+        // Check if route has @ignore tag
+        if (dataTypes.isIgnored) {
+            return true;
+        }
+        // Check if route matches any ignore patterns
+        const ignorePatterns = this.config.ignoreRoutes || [];
+        if (ignorePatterns.length === 0) {
+            return false;
+        }
+        return ignorePatterns.some((pattern) => {
+            // Support wildcards
+            const regexPattern = pattern.replace(/\*/g, ".*").replace(/\//g, "\\/");
+            const regex = new RegExp(`^${regexPattern}$`);
+            return regex.test(routePath);
+        });
+    }
     processFile(filePath) {
         // Check if the file has already been processed
         if (this.processFileTracker[filePath])
             return;
         const content = fs.readFileSync(filePath, "utf-8");
         const ast = parseTypeScriptFile(content);
-        traverse.default(ast, {
+        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 routePath = this.getRoutePath(filePath);
                             const pathParams = extractPathParameters(routePath);
                             // If we have path parameters but no pathParamsType defined, we should log a warning
                             if (pathParams.length > 0 && !dataTypes.pathParamsType) {
@@ -144,10 +172,15 @@ export class RouteProcessor {
                         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 routePath = this.getRoutePath(filePath);
                                     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.`);
@@ -243,7 +276,28 @@ export class RouteProcessor {
         }
         // Add request body
         if (MUTATION_HTTP_METHODS.includes(method.toUpperCase())) {
-            definition.requestBody = this.schemaProcessor.createRequestBodySchema(body, bodyDescription, dataTypes.contentType);
+            if (dataTypes.bodyType) {
+                // Ensure the schema is defined in components/schemas
+                this.schemaProcessor.getSchemaContent({
+                    bodyType: dataTypes.bodyType,
+                });
+                // Use reference to the schema
+                const contentType = this.schemaProcessor.detectContentType(dataTypes.bodyType || "", dataTypes.contentType);
+                definition.requestBody = {
+                    content: {
+                        [contentType]: {
+                            schema: { $ref: `#/components/schemas/${dataTypes.bodyType}` },
+                        },
+                    },
+                };
+                if (bodyDescription) {
+                    definition.requestBody.description = bodyDescription;
+                }
+            }
+            else if (body && Object.keys(body).length > 0) {
+                // Fallback to inline schema for backward compatibility
+                definition.requestBody = this.schemaProcessor.createRequestBodySchema(body, bodyDescription, dataTypes.contentType);
+            }
         }
         // Add responses
         definition.responses = this.buildResponsesFromConfig(dataTypes, method);
@@ -256,15 +310,15 @@ export class RouteProcessor {
         this.swaggerPaths[routePath][method] = definition;
     }
     getRoutePath(filePath) {
+        // Normalize path separators first
+        const normalizedPath = filePath.replaceAll("\\", "/");
         // First, check if it's an app router path
-        if (filePath.includes("/app/api/")) {
+        if (normalizedPath.includes("/app/api/")) {
             // Get the relative path from the api directory
-            const apiDirPos = filePath.indexOf("/app/api/");
-            let relativePath = filePath.substring(apiDirPos + "/app/api".length);
+            const apiDirPos = normalizedPath.lastIndexOf("/app/api/");
+            let relativePath = normalizedPath.substring(apiDirPos + "/app/api".length);
             // Remove the /route.ts or /route.tsx suffix
             relativePath = relativePath.replace(/\/route\.tsx?$/, "");
-            // Convert directory separators to URL path format
-            relativePath = relativePath.replaceAll("\\", "/");
             // Remove Next.js route groups (folders in parentheses like (authenticated), (marketing))
             relativePath = relativePath.replace(/\/\([^)]+\)/g, "");
             // Convert Next.js dynamic route syntax to OpenAPI parameter syntax
@@ -274,10 +328,9 @@ export class RouteProcessor {
             return relativePath;
         }
         // For pages router or other formats
-        const suffixPath = filePath.split("api")[1];
+        const suffixPath = normalizedPath.split("api")[1];
         return suffixPath
             .replace(/route\.tsx?$/, "")
-            .replaceAll("\\", "/")
             .replace(/\/$/, "")
             .replace(/\/\([^)]+\)/g, "") // Remove route groups for pages router too
             .replace(/\/\[([^\]]+)\]/g, "/{$1}") // Replace [param] with {param}

package/dist/lib/schema-processor.js

@@ -1,7 +1,9 @@
 import fs from "fs";
 import path from "path";
-import traverse from "@babel/traverse";
+import traverseModule from "@babel/traverse";
 import * as t from "@babel/types";
+// Handle both ES modules and CommonJS
+const traverse = traverseModule.default || traverseModule;
 import { parseTypeScriptFile } from "./utils.js";
 import { ZodSchemaConverter } from "./zod-converter.js";
 import { logger } from "./logger.js";
@@ -28,20 +30,31 @@ export class SchemaProcessor {
      * Get all defined schemas (for components.schemas section)
      */
     getDefinedSchemas() {
+        // Filter out generic type parameters and invalid schema names
+        const filteredSchemas = {};
+        Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
+            if (!this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key)) {
+                filteredSchemas[key] = value;
+            }
+        });
         // If using Zod, also include all processed Zod schemas
         if (this.schemaType === "zod" && this.zodSchemaConverter) {
             const zodSchemas = this.zodSchemaConverter.getProcessedSchemas();
             return {
-                ...this.openapiDefinitions,
+                ...filteredSchemas,
                 ...zodSchemas,
             };
         }
-        return this.openapiDefinitions;
+        return filteredSchemas;
     }
     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 >)
+        if (schemaName.includes("<") && schemaName.includes(">")) {
+            return this.resolveGenericTypeFromString(schemaName);
+        }
         // Check if we should use Zod schemas
         if (this.schemaType === "zod") {
             logger.debug(`Looking for Zod schema: ${schemaName}`);
@@ -85,7 +98,7 @@ export class SchemaProcessor {
         });
     }
     collectTypeDefinitions(ast, schemaName) {
-        traverse.default(ast, {
+        traverse(ast, {
             VariableDeclarator: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
                     const name = path.node.id.name;
@@ -95,7 +108,14 @@ export class SchemaProcessor {
             TSTypeAliasDeclaration: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
                     const name = path.node.id.name;
-                    this.typeDefinitions[name] = path.node.typeAnnotation;
+                    // 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
+                    }
                 }
             },
             TSInterfaceDeclaration: (path) => {
@@ -150,6 +170,13 @@ export class SchemaProcessor {
             const typeNode = this.typeDefinitions[typeName.toString()];
             if (!typeNode)
                 return {};
+            // Handle generic type alias declarations (full node)
+            if (t.isTSTypeAliasDeclaration(typeNode)) {
+                // This is a generic type, should be handled by the caller via resolveGenericType
+                // For non-generic access, just return the type annotation
+                const typeAnnotation = typeNode.typeAnnotation;
+                return this.resolveTSNodeType(typeAnnotation);
+            }
             // Check if node is Zod
             if (t.isCallExpression(typeNode) &&
                 t.isMemberExpression(typeNode.callee) &&
@@ -350,6 +377,16 @@ export class SchemaProcessor {
                     return this.resolveTSNodeType(node.typeParameters.params[0]);
                 }
             }
+            // Handle custom generic types
+            if (node.typeParameters && node.typeParameters.params.length > 0) {
+                // Find the generic type definition first
+                this.findSchemaDefinition(typeName, this.contentType);
+                const genericTypeDefinition = this.typeDefinitions[typeName];
+                if (genericTypeDefinition) {
+                    // Resolve the generic type by substituting type parameters
+                    return this.resolveGenericType(genericTypeDefinition, node.typeParameters.params, typeName);
+                }
+            }
             // Check if it is a type that we are already processing
             if (this.processingTypes.has(typeName)) {
                 return { $ref: `#/components/schemas/${typeName}` };
@@ -768,4 +805,275 @@ export class SchemaProcessor {
             responses,
         };
     }
+    /**
+     * Parse and resolve a generic type from a string like "MyApiSuccessResponseBody<LLMSResponse>"
+     * @param genericTypeString - The generic type string to parse and resolve
+     * @returns The resolved OpenAPI schema
+     */
+    resolveGenericTypeFromString(genericTypeString) {
+        // Parse the generic type string
+        const parsed = this.parseGenericTypeString(genericTypeString);
+        if (!parsed) {
+            return {};
+        }
+        const { baseTypeName, typeArguments } = parsed;
+        // Find the base generic type definition
+        this.scanSchemaDir(this.schemaDir, baseTypeName);
+        const genericTypeDefinition = this.typeDefinitions[baseTypeName];
+        if (!genericTypeDefinition) {
+            logger.debug(`Generic type definition not found for: ${baseTypeName}`);
+            return {};
+        }
+        // Also find all the type argument definitions
+        typeArguments.forEach((argTypeName) => {
+            // If it's a simple type reference (not another generic), find its definition
+            if (!argTypeName.includes("<") &&
+                !this.isGenericTypeParameter(argTypeName)) {
+                this.scanSchemaDir(this.schemaDir, argTypeName);
+            }
+        });
+        // Create AST nodes for the type arguments by parsing them
+        const typeArgumentNodes = typeArguments.map((arg) => this.createTypeNodeFromString(arg));
+        // Resolve the generic type
+        const resolved = this.resolveGenericType(genericTypeDefinition, typeArgumentNodes, baseTypeName);
+        // Cache the resolved type for future reference
+        this.openapiDefinitions[genericTypeString] = resolved;
+        return resolved;
+    }
+    /**
+     * Check if a type name is likely a generic type parameter (e.g., T, U, K, V)
+     * @param {string} typeName - The type name to check
+     * @returns {boolean} - True if it's likely a generic type parameter
+     */
+    isGenericTypeParameter(typeName) {
+        // Common generic type parameter patterns:
+        // - Single uppercase letters (T, U, K, V, etc.)
+        // - TKey, TValue, etc.
+        return /^[A-Z]$|^T[A-Z][a-zA-Z]*$/.test(typeName);
+    }
+    /**
+     * Check if a schema name is invalid (contains special characters, brackets, etc.)
+     * @param {string} schemaName - The schema name to check
+     * @returns {boolean} - True if the schema name is invalid
+     */
+    isInvalidSchemaName(schemaName) {
+        // Schema names should not contain { } : ? spaces or other special characters
+        return /[{}\s:?]/.test(schemaName);
+    }
+    /**
+     * Parse a generic type string into base type and arguments
+     * @param genericTypeString - The string like "MyApiSuccessResponseBody<LLMSResponse>"
+     * @returns Object with baseTypeName and typeArguments array
+     */
+    parseGenericTypeString(genericTypeString) {
+        const match = genericTypeString.match(/^([^<]+)<(.+)>$/);
+        if (!match) {
+            return null;
+        }
+        const baseTypeName = match[1].trim();
+        const typeArgsString = match[2].trim();
+        // Split type arguments by comma, handling nested generics
+        const typeArguments = this.splitTypeArguments(typeArgsString);
+        return { baseTypeName, typeArguments };
+    }
+    /**
+     * Split type arguments by comma, handling nested generics correctly
+     * @param typeArgsString - The string inside angle brackets
+     * @returns Array of individual type argument strings
+     */
+    splitTypeArguments(typeArgsString) {
+        const args = [];
+        let currentArg = "";
+        let bracketDepth = 0;
+        for (let i = 0; i < typeArgsString.length; i++) {
+            const char = typeArgsString[i];
+            if (char === "<") {
+                bracketDepth++;
+            }
+            else if (char === ">") {
+                bracketDepth--;
+            }
+            else if (char === "," && bracketDepth === 0) {
+                args.push(currentArg.trim());
+                currentArg = "";
+                continue;
+            }
+            currentArg += char;
+        }
+        if (currentArg.trim()) {
+            args.push(currentArg.trim());
+        }
+        return args;
+    }
+    /**
+     * Create a TypeScript AST node from a type string
+     * @param typeString - The type string like "LLMSResponse"
+     * @returns A TypeScript AST node
+     */
+    createTypeNodeFromString(typeString) {
+        // For simple type references, create a TSTypeReference node
+        if (!typeString.includes("<")) {
+            return {
+                type: "TSTypeReference",
+                typeName: {
+                    type: "Identifier",
+                    name: typeString,
+                },
+            };
+        }
+        // For nested generics, recursively parse
+        const parsed = this.parseGenericTypeString(typeString);
+        if (parsed) {
+            const typeParameterNodes = parsed.typeArguments.map((arg) => this.createTypeNodeFromString(arg));
+            return {
+                type: "TSTypeReference",
+                typeName: {
+                    type: "Identifier",
+                    name: parsed.baseTypeName,
+                },
+                typeParameters: {
+                    type: "TSTypeParameterInstantiation",
+                    params: typeParameterNodes,
+                },
+            };
+        }
+        // Fallback for unknown patterns
+        return {
+            type: "TSTypeReference",
+            typeName: {
+                type: "Identifier",
+                name: typeString,
+            },
+        };
+    }
+    /**
+     * Resolve generic types by substituting type parameters with actual types
+     * @param genericTypeDefinition - The AST node of the generic type definition
+     * @param typeArguments - The type arguments passed to the generic type
+     * @param typeName - The name of the generic type
+     * @returns The resolved OpenAPI schema
+     */
+    resolveGenericType(genericTypeDefinition, typeArguments, typeName) {
+        // Extract type parameters from the generic type definition
+        let typeParameters = [];
+        if (t.isTSTypeAliasDeclaration(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;
+                });
+            }
+            // 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);
+        }
+        // If we can't process the generic type, return empty object
+        return {};
+    }
+    /**
+     * Resolve a type node with type parameter substitution
+     * @param node - The AST node to resolve
+     * @param typeParameterMap - Mapping from type parameter names to actual types
+     * @returns The resolved OpenAPI schema
+     */
+    resolveTypeWithSubstitution(node, typeParameterMap) {
+        if (!node)
+            return { type: "object" };
+        // If this is a type parameter reference, substitute it
+        if (t.isTSTypeReference(node) && t.isIdentifier(node.typeName)) {
+            const paramName = node.typeName.name;
+            if (typeParameterMap[paramName]) {
+                // The mapped value is an AST node, resolve it
+                const mappedNode = typeParameterMap[paramName];
+                if (t.isTSTypeReference(mappedNode) &&
+                    t.isIdentifier(mappedNode.typeName)) {
+                    // If it's a reference to another type, get the resolved schema from openapiDefinitions
+                    const referencedTypeName = mappedNode.typeName.name;
+                    if (this.openapiDefinitions[referencedTypeName]) {
+                        return this.openapiDefinitions[referencedTypeName];
+                    }
+                    // If not in openapiDefinitions, try to resolve it
+                    this.findSchemaDefinition(referencedTypeName, this.contentType);
+                    return this.openapiDefinitions[referencedTypeName] || {};
+                }
+                return this.resolveTSNodeType(typeParameterMap[paramName]);
+            }
+        }
+        // Handle intersection types (e.g., T & { success: true })
+        if (t.isTSIntersectionType(node)) {
+            const allProperties = {};
+            const requiredProperties = [];
+            node.types.forEach((typeNode, index) => {
+                let resolvedType;
+                // Check if this is a type parameter reference
+                if (t.isTSTypeReference(typeNode) &&
+                    t.isIdentifier(typeNode.typeName)) {
+                    const paramName = typeNode.typeName.name;
+                    if (typeParameterMap[paramName]) {
+                        const mappedNode = typeParameterMap[paramName];
+                        if (t.isTSTypeReference(mappedNode) &&
+                            t.isIdentifier(mappedNode.typeName)) {
+                            // If it's a reference to another type, get the resolved schema
+                            const referencedTypeName = mappedNode.typeName.name;
+                            if (this.openapiDefinitions[referencedTypeName]) {
+                                resolvedType = this.openapiDefinitions[referencedTypeName];
+                            }
+                            else {
+                                // If not in openapiDefinitions, try to resolve it
+                                this.findSchemaDefinition(referencedTypeName, this.contentType);
+                                resolvedType =
+                                    this.openapiDefinitions[referencedTypeName] || {};
+                            }
+                        }
+                        else {
+                            resolvedType = this.resolveTSNodeType(mappedNode);
+                        }
+                    }
+                    else {
+                        resolvedType = this.resolveTSNodeType(typeNode);
+                    }
+                }
+                else {
+                    resolvedType = this.resolveTypeWithSubstitution(typeNode, typeParameterMap);
+                }
+                if (resolvedType.type === "object" && resolvedType.properties) {
+                    Object.entries(resolvedType.properties).forEach(([key, value]) => {
+                        allProperties[key] = value;
+                        if (value.required) {
+                            requiredProperties.push(key);
+                        }
+                    });
+                }
+            });
+            return {
+                type: "object",
+                properties: allProperties,
+                required: requiredProperties.length > 0 ? requiredProperties : undefined,
+            };
+        }
+        // For other types, use the standard resolution but with parameter substitution
+        if (t.isTSTypeLiteral(node)) {
+            const properties = {};
+            node.members.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);
+    }
 }

package/dist/lib/utils.js

@@ -25,6 +25,7 @@ export function extractJSDocComments(path) {
     let bodyType = "";
     let auth = "";
     let isOpenApi = false;
+    let isIgnored = false;
     let deprecated = false;
     let bodyDescription = "";
     let contentType = "";
@@ -37,6 +38,9 @@ export function extractJSDocComments(path) {
         comments.forEach((comment) => {
             const commentValue = cleanComment(comment.value);
             isOpenApi = commentValue.includes("@openapi");
+            if (commentValue.includes("@ignore")) {
+                isIgnored = true;
+            }
             if (commentValue.includes("@deprecated")) {
                 deprecated = true;
             }
@@ -121,15 +125,12 @@ export function extractJSDocComments(path) {
                 }
             }
             if (commentValue.includes("@response")) {
-                const responseMatch = commentValue.match(/@response\s+(?:(\d+):)?(\w+)(?::(.*))?/);
+                // Updated regex to support generic types
+                const responseMatch = commentValue.match(/@response\s+(?:(\d+):)?([^@\n\r]+)(?:\s+(.*))?/);
                 if (responseMatch) {
-                    const [, code, type, description] = responseMatch;
+                    const [, code, type] = responseMatch;
                     successCode = code || "";
-                    responseType = type;
-                    // Set responseDescription only if not already set by @responseDescription
-                    if (description?.trim() && !responseDescription) {
-                        responseDescription = description.trim();
-                    }
+                    responseType = type?.trim();
                 }
                 else {
                     responseType = extractTypeFromComment(commentValue, "@response");
@@ -146,6 +147,7 @@ export function extractJSDocComments(path) {
         pathParamsType,
         bodyType,
         isOpenApi,
+        isIgnored,
         deprecated,
         bodyDescription,
         contentType,
@@ -157,7 +159,10 @@ export function extractJSDocComments(path) {
     };
 }
 export function extractTypeFromComment(commentValue, tag) {
-    return commentValue.match(new RegExp(`${tag}\\s*\\s*(\\w+)`))?.[1] || "";
+    // Updated regex to support generic types with angle brackets
+    return (commentValue
+        .match(new RegExp(`${tag}\\s*\\s*([\\w<>,\\s]+)`))?.[1]
+        ?.trim() || "");
 }
 export function cleanComment(commentValue) {
     return commentValue.replace(/\*\s*/g, "").trim();
@@ -170,6 +175,7 @@ export function cleanSpec(spec) {
         "ui",
         "outputFile",
         "includeOpenApiRoutes",
+        "ignoreRoutes",
         "schemaType",
         "defaultResponseSet",
         "responseSets",

package/dist/lib/zod-converter.js

@@ -1,7 +1,9 @@
 import fs from "fs";
 import path from "path";
-import traverse from "@babel/traverse";
+import traverseModule from "@babel/traverse";
 import * as t from "@babel/types";
+// Handle both ES modules and CommonJS
+const traverse = traverseModule.default || traverseModule;
 import { parseTypeScriptFile } from "./utils.js";
 import { logger } from "./logger.js";
 /**
@@ -150,7 +152,7 @@ export class ZodSchemaConverter {
             // Create a map to store imported modules
             const importedModules = {};
             // Look for all exported Zod schemas
-            traverse.default(ast, {
+            traverse(ast, {
                 // Track imports for resolving local and imported schemas
                 ImportDeclaration: (path) => {
                     // Keep track of imports to resolve external schemas
@@ -457,7 +459,7 @@ export class ZodSchemaConverter {
         try {
             const content = fs.readFileSync(filePath, "utf-8");
             const ast = parseTypeScriptFile(content);
-            traverse.default(ast, {
+            traverse(ast, {
                 ExportNamedDeclaration: (path) => {
                     if (t.isVariableDeclaration(path.node.declaration)) {
                         path.node.declaration.declarations.forEach((declaration) => {
@@ -1353,7 +1355,7 @@ export class ZodSchemaConverter {
         try {
             const content = fs.readFileSync(filePath, "utf-8");
             const ast = parseTypeScriptFile(content);
-            traverse.default(ast, {
+            traverse(ast, {
                 TSTypeAliasDeclaration: (path) => {
                     if (t.isIdentifier(path.node.id)) {
                         const typeName = path.node.id.name;
@@ -1421,7 +1423,7 @@ export class ZodSchemaConverter {
             const content = fs.readFileSync(filePath, "utf-8");
             const ast = parseTypeScriptFile(content);
             // Collect all exported Zod schemas
-            traverse.default(ast, {
+            traverse(ast, {
                 ExportNamedDeclaration: (path) => {
                     if (t.isVariableDeclaration(path.node.declaration)) {
                         path.node.declaration.declarations.forEach((declaration) => {

package/dist/openapi-template.js

@@ -93,5 +93,6 @@ export default {
     outputFile: "openapi.json",
     outputDir: "./public",
     includeOpenApiRoutes: false,
+    ignoreRoutes: [],
     debug: false,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "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",
@@ -13,8 +13,13 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
-    "prepare": "npm run build"
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
   },
   "repository": {
     "type": "git",
@@ -51,6 +56,8 @@
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
-    "typescript": "^5.9.2"
+    "@vitest/ui": "^3.2.4",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
   }
 }