feat: add isCollection support for DataResponse attribute

Author: Daniel Held

src/Attributes/DataResponse.php

@@ -9,5 +9,11 @@
 #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
 class DataResponse
 {
-    public function __construct(public int $status, public string $description = '', public null|string|array $resource = [], public array $headers = []) {}
+    public function __construct(
+        public int $status,
+        public string $description = '',
+        public null|string|array $resource = [],
+        public array $headers = [],
+        public bool $isCollection = false,
+    ) {}
 }

src/Services/EnhancedResponseAnalyzer.php

@@ -564,6 +564,15 @@ public function analyzeResourceNew(New_ $node, string $controller, string $metho
 
         $resourceClass = $node->class->toString();
 
+        if (!class_exists($resourceClass)) {
+            $resolvedClass = $this->resolveClassNameFromController($resourceClass, $controller);
+            if ($resolvedClass && class_exists($resolvedClass)) {
+                $resourceClass = $resolvedClass;
+            } else {
+                return;
+            }
+        }
+
         // Use existing ResponseAnalyzer for resource analysis
         $analysis = $this->responseAnalyzer->analyzeJsonResourceResponse($resourceClass);
 
@@ -579,6 +588,50 @@ public function analyzeResourceNew(New_ $node, string $controller, string $metho
         }
     }
 
+    private function resolveClassNameFromController(string $shortClassName, string $controllerClass): ?string
+    {
+        if (!class_exists($controllerClass)) {
+            return null;
+        }
+
+        try {
+            $reflection = new \ReflectionClass($controllerClass);
+            $filename = $reflection->getFileName();
+
+            if (!$filename || !file_exists($filename)) {
+                return null;
+            }
+
+            $content = file_get_contents($filename);
+            $namespace = $reflection->getNamespaceName();
+
+            if (preg_match('/^use\s+([^\s;]+\\\\' . preg_quote($shortClassName, '/') . ')\s*;/m', $content, $matches)) {
+                return $matches[1];
+            }
+
+            $sameNamespaceClass = $namespace . '\\' . $shortClassName;
+            if (class_exists($sameNamespaceClass)) {
+                return $sameNamespaceClass;
+            }
+
+            $resourceNamespaces = [
+                str_replace('\\Controllers\\', '\\Resources\\', $namespace),
+                str_replace('\\Http\\Controllers\\', '\\Http\\Resources\\', $namespace),
+            ];
+
+            foreach ($resourceNamespaces as $resourceNamespace) {
+                $potentialClass = $resourceNamespace . '\\' . $shortClassName;
+                if (class_exists($potentialClass)) {
+                    return $potentialClass;
+                }
+            }
+
+            return null;
+        } catch (\Throwable $e) {
+            return null;
+        }
+    }
+
     /**
      * Detect resource wrapping configuration with inheritance support
      */
@@ -735,6 +788,7 @@ private function processDataResponseAttributes(ReflectionMethod $method): void
             $description = $instance->description ?: $this->getStatusDescription($statusCode);
             $resource = $instance->resource;
             $headers = $instance->headers;
+            $isCollection = $instance->isCollection;
 
             // Create response schema based on resource if specified
             $schema = null;
@@ -752,7 +806,8 @@ private function processDataResponseAttributes(ReflectionMethod $method): void
                     'application/json',
                     $schema,
                     $headers,
-                    is_string($resource) ? $resource : null
+                    is_string($resource) ? $resource : null,
+                    $isCollection
                 );
             } else {
                 $this->addResponse($statusCode, $description, 'application/json', $schema, $headers);
@@ -1426,22 +1481,45 @@ private function addResponse(string $statusCode, string $description, ?string $c
     /**
      * Add success response with detailed schema analysis
      */
-    private function addSuccessResponse(string $statusCode, string $description, string $controller, string $method, ?string $contentType = 'application/json', ?array $additionalSchema = null, array $headers = [], ?string $resourceClass = null): void
+    private function addSuccessResponse(string $statusCode, string $description, string $controller, string $method, ?string $contentType = 'application/json', ?array $additionalSchema = null, array $headers = [], ?string $resourceClass = null, bool $isCollection = false): void
     {
         if (! isset($this->detectedResponses[$statusCode])) {
             // Use existing ResponseAnalyzer for detailed schema analysis
             $detailedSchema = $this->responseAnalyzer->analyzeControllerMethod($controller, $method);
 
-            // Merge with any additional schema information
-            if ($additionalSchema) {
+            // Prefer additionalSchema (from resource class) if provided and has properties
+            if ($additionalSchema && !empty($additionalSchema['properties'])) {
+                $detailedSchema = $additionalSchema;
+            } elseif ($additionalSchema) {
                 $detailedSchema = array_merge($detailedSchema ?: [], $additionalSchema);
             }
 
             // Apply Parameter attributes to enhance the schema
             $detailedSchema = $this->applyParameterAttributesToSchema($detailedSchema, $controller, $method);
 
+            // Wrap schema in array if isCollection is true
+            if ($isCollection) {
+                // Ensure we have at least a basic schema for collections
+                if (empty($detailedSchema)) {
+                    $detailedSchema = [
+                        'type' => 'object',
+                        'properties' => [],
+                    ];
+                }
+
+                $detailedSchema = [
+                    'type' => 'array',
+                    'items' => $detailedSchema,
+                ];
+            }
+
             // Generate MediaType-level example from schema property examples
-            $responseExample = $this->generateResponseExampleFromSchema($detailedSchema);
+            $responseExample = $this->generateResponseExampleFromSchema($isCollection ? ($detailedSchema['items'] ?? null) : $detailedSchema);
+
+            // Wrap example in array if isCollection is true
+            if ($isCollection && $responseExample) {
+                $responseExample = [$responseExample];
+            }
 
             $response = [
                 'description' => $description,

src/Services/ResponseAnalyzer.php

@@ -896,6 +896,19 @@ public function analyzeJsonResourceResponse(string $resourceClass): array
                     'enhanced_analysis' => true,
                 ];
             }
+
+            // Fallback for classes that are neither ResourceCollection nor JsonResource
+            return [
+                'type' => 'object',
+                'properties' => [
+                    'data' => [
+                        'type' => 'object',
+                        'description' => 'Resource data',
+                    ],
+                ],
+                'example' => ['data' => []],
+                'enhanced_analysis' => true,
+            ];
         } catch (Throwable $e) {
             return [
                 'type' => 'object',

src/Services/RouteComposition.php

@@ -590,6 +590,10 @@ private function normalizeEnhancedResponses(array $enhancedResponses): array
                 'detection_method' => 'enhanced_ast_analysis',
             ];
 
+            if (isset($response['schema']['items'])) {
+                $normalizedResponses[$statusCode]['items'] = $response['schema']['items'];
+            }
+
             // Include resource if available
             if (isset($response['resource'])) {
                 $normalizedResponses[$statusCode]['resource'] = $response['resource'];