fix: support array notation in @response and @Body annotations (Type[]) (#55)

Author: tazo90

examples/next15-app-drizzle-zod/public/openapi.json

@@ -72,7 +72,10 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostResponseSchema[]"
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/PostResponseSchema"
+                  }
                 }
               }
             }
@@ -303,7 +306,55 @@
           }
         }
       },
-      "PostResponseSchema[]": {},
+      "PostResponseSchema": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Post title"
+          },
+          "slug": {
+            "type": "string",
+            "description": "URL-friendly slug"
+          },
+          "excerpt": {
+            "type": "string",
+            "description": "Post excerpt"
+          },
+          "content": {
+            "type": "string",
+            "description": "Full post content"
+          },
+          "published": {
+            "type": "boolean",
+            "description": "Publication status"
+          },
+          "viewCount": {
+            "type": "integer",
+            "description": "Number of views"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Creation timestamp"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Last update timestamp"
+          }
+        },
+        "required": [
+          "title",
+          "slug",
+          "excerpt",
+          "content",
+          "published",
+          "viewCount",
+          "createdAt",
+          "updatedAt"
+        ]
+      },
       "CreatePostSchema": {
         "type": "object",
         "properties": {
@@ -361,55 +412,6 @@
           "id"
         ]
       },
-      "PostResponseSchema": {
-        "type": "object",
-        "properties": {
-          "title": {
-            "type": "string",
-            "description": "Post title"
-          },
-          "slug": {
-            "type": "string",
-            "description": "URL-friendly slug"
-          },
-          "excerpt": {
-            "type": "string",
-            "description": "Post excerpt"
-          },
-          "content": {
-            "type": "string",
-            "description": "Full post content"
-          },
-          "published": {
-            "type": "boolean",
-            "description": "Publication status"
-          },
-          "viewCount": {
-            "type": "integer",
-            "description": "Number of views"
-          },
-          "createdAt": {
-            "type": "string",
-            "format": "date-time",
-            "description": "Creation timestamp"
-          },
-          "updatedAt": {
-            "type": "string",
-            "format": "date-time",
-            "description": "Last update timestamp"
-          }
-        },
-        "required": [
-          "title",
-          "slug",
-          "excerpt",
-          "content",
-          "published",
-          "viewCount",
-          "createdAt",
-          "updatedAt"
-        ]
-      },
       "UpdatePostSchema": {
         "type": "object",
         "properties": {

examples/next15-app-zod/public/openapi.json

@@ -2326,7 +2326,7 @@
     "/users-paginated": {
       "get": {
         "operationId": "get-users-paginated",
-        "summary": "Get paginated users",
+        "summary": "Get paginated users\r",
         "description": "Retrieve users with cursor-based pagination using factory-generated schema",
         "tags": [
           "Users-paginated"

src/lib/route-processor.ts

@@ -48,16 +48,42 @@ export class RouteProcessor {
     const successCode =
       dataTypes.successCode || this.getDefaultSuccessCode(method);
     if (dataTypes.responseType) {
-      // Ensure the schema is defined in components/schemas
+      // Handle array notation (e.g., "Type[]", "Type[][]", "Generic<T>[]")
+      let schema: any;
+      let baseType = dataTypes.responseType;
+      let arrayDepth = 0;
+
+      // Count and remove array brackets
+      while (baseType.endsWith('[]')) {
+        arrayDepth++;
+        baseType = baseType.slice(0, -2);
+      }
+
+      // Ensure the base schema is defined in components/schemas
       this.schemaProcessor.getSchemaContent({
-        responseType: dataTypes.responseType,
+        responseType: baseType,
       });
 
+      // Build schema reference
+      if (arrayDepth === 0) {
+        // Not an array
+        schema = { $ref: `#/components/schemas/${baseType}` };
+      } else {
+        // Build nested array schema
+        schema = { $ref: `#/components/schemas/${baseType}` };
+        for (let i = 0; i < arrayDepth; i++) {
+          schema = {
+            type: "array",
+            items: schema,
+          };
+        }
+      }
+
       responses[successCode] = {
         description: dataTypes.responseDescription || "Successful response",
         content: {
           "application/json": {
-            schema: { $ref: `#/components/schemas/${dataTypes.responseType}` },
+            schema: schema,
           },
         },
       };

src/lib/schema-processor.ts

@@ -1059,12 +1059,26 @@ export class SchemaProcessor {
     body: OpenAPIDefinition;
     responses: OpenAPIDefinition;
   } {
+    // Helper function to strip array notation from type names
+    const stripArrayNotation = (typeName: string | undefined): string | undefined => {
+      if (!typeName) return typeName;
+      let baseType = typeName;
+      while (baseType.endsWith('[]')) {
+        baseType = baseType.slice(0, -2);
+      }
+      return baseType;
+    };
+
+    // 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 = bodyType ? this.openapiDefinitions[bodyType] : {};
-    let responses = responseType ? this.openapiDefinitions[responseType] : {};
+    let body = baseBodyType ? this.openapiDefinitions[baseBodyType] : {};
+    let responses = baseResponseType ? this.openapiDefinitions[baseResponseType] : {};
 
     if (paramsType && !params) {
       this.findSchemaDefinition(paramsType, "params");
@@ -1076,22 +1090,22 @@ export class SchemaProcessor {
       pathParams = this.openapiDefinitions[pathParamsType] || {};
     }
 
-    if (bodyType && !body) {
-      this.findSchemaDefinition(bodyType, "body");
-      body = this.openapiDefinitions[bodyType] || {};
+    if (baseBodyType && !body) {
+      this.findSchemaDefinition(baseBodyType, "body");
+      body = this.openapiDefinitions[baseBodyType] || {};
     }
 
-    if (responseType && !responses) {
-      this.findSchemaDefinition(responseType, "response");
-      responses = this.openapiDefinitions[responseType] || {};
+    if (baseResponseType && !responses) {
+      this.findSchemaDefinition(baseResponseType, "response");
+      responses = this.openapiDefinitions[baseResponseType] || {};
     }
 
     if (this.schemaTypes.includes("zod")) {
       const schemasToProcess = [
         paramsType,
         pathParamsType,
-        bodyType,
-        responseType,
+        baseBodyType,
+        baseResponseType,
       ].filter(Boolean);
       schemasToProcess.forEach((schemaName) => {
         if (!this.openapiDefinitions[schemaName]) {

src/lib/utils.ts

@@ -193,10 +193,10 @@ export function extractTypeFromComment(
   commentValue: string,
   tag: string
 ): string {
-  // Updated regex to support generic types with angle brackets
+  // Updated regex to support generic types with angle brackets and array brackets
   return (
     commentValue
-      .match(new RegExp(`${tag}\\s*\\s*([\\w<>,\\s]+)`))?.[1]
+      .match(new RegExp(`${tag}\\s*\\s*([\\w<>,\\s\\[\\]]+)`))?.[1]
       ?.trim() || ""
   );
 }