next-openapi-gen 0.7.7 → 0.7.9

package/README.md

@@ -554,6 +554,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/route-processor.js

@@ -23,14 +23,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}` },
                     },
                 },
             };
@@ -243,7 +244,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);

package/dist/lib/schema-processor.js

@@ -28,20 +28,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}`);
@@ -95,7 +106,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 +168,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 +375,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 +803,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

@@ -48,7 +48,11 @@ export function extractJSDocComments(path) {
                 }
             }
             if (!summary) {
-                summary = commentValue.split("\n")[0];
+                const firstLine = commentValue.split("\n")[0];
+                // Don't use tags as summary - only use actual descriptions
+                if (!firstLine.trim().startsWith("@")) {
+                    summary = firstLine;
+                }
             }
             if (commentValue.includes("@auth")) {
                 const regex = /@auth\s*(.*)/;
@@ -117,15 +121,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");
@@ -153,7 +154,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();

package/dist/lib/zod-converter.js

@@ -855,22 +855,6 @@ export class ZodSchemaConverter {
             !t.isIdentifier(node.callee.property)) {
             return { type: "string" };
         }
-        if (t.isMemberExpression(node.callee) &&
-            t.isIdentifier(node.callee.property)) {
-            const zodType = node.callee.property.name;
-            // Custom() support for FormData
-            if (zodType === "custom" && node.arguments.length > 0) {
-                // Check if it is FormData
-                if (t.isArrowFunctionExpression(node.arguments[0])) {
-                    // Assume custom FormData validation
-                    return {
-                        type: "object",
-                        additionalProperties: true,
-                        description: "Form data object",
-                    };
-                }
-            }
-        }
         const zodType = node.callee.property.name;
         let schema = {};
         // Basic type mapping
@@ -990,6 +974,37 @@ export class ZodSchemaConverter {
                     schema = { type: "object" };
                 }
                 break;
+            case "custom":
+                // Check if it has TypeScript generic type parameters (z.custom<File>())
+                if (node.typeParameters && node.typeParameters.params.length > 0) {
+                    const typeParam = node.typeParameters.params[0];
+                    // Check if the generic type is File
+                    if (t.isTSTypeReference(typeParam) &&
+                        t.isIdentifier(typeParam.typeName) &&
+                        typeParam.typeName.name === "File") {
+                        schema = {
+                            type: "string",
+                            format: "binary",
+                        };
+                    }
+                    else {
+                        // Other generic types default to string
+                        schema = { type: "string" };
+                    }
+                }
+                else if (node.arguments.length > 0 &&
+                    t.isArrowFunctionExpression(node.arguments[0])) {
+                    // Legacy support: FormData validation
+                    schema = {
+                        type: "object",
+                        additionalProperties: true,
+                    };
+                }
+                else {
+                    // Default case for z.custom() without specific type detection
+                    schema = { type: "string" };
+                }
+                break;
             default:
                 schema = { type: "string" };
                 break;

package/package.json

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