added support for arrays of arbitrary depths

Author: eceltov

app/helpers/MetaFormats/RequestParamData.php

@@ -112,9 +112,11 @@ public function toAnnotationParameterData()
 
         // determine swagger type
         $nestedArraySwaggerType = null;
+        $arrayDepth = null;
         $swaggerType = $this->validators[0]::SWAGGER_TYPE;
-        // extract array element type
+        // extract array depth and element type
         if ($this->validators[0] instanceof VArray) {
+            $arrayDepth = $this->validators[0]->getArrayDepth();
             $nestedArraySwaggerType = $this->validators[0]->getElementSwaggerType();
         }
 
@@ -150,6 +152,7 @@ public function toAnnotationParameterData()
             $this->nullable,
             $exampleValue,
             $nestedArraySwaggerType,
+            $arrayDepth,
             $nestedObjectParameterData,
             $constraints,
         );

app/helpers/MetaFormats/Validators/VArray.php

@@ -2,6 +2,8 @@
 
 namespace App\Helpers\MetaFormats\Validators;
 
+use App\Helpers\Swagger\ParameterConstraints;
+
 /**
  * Validates arrays and their nested elements.
  */
@@ -33,17 +35,45 @@ public function getExampleValue(): string | null
     }
 
     /**
-     * @return string|null Returns the element swagger type. Can be null if the element validator is not set.
+     * @return string|null Returns the bottommost element swagger type. Can be null if the element validator is not set.
      */
     public function getElementSwaggerType(): mixed
     {
+        // return null if the element type is unspecified
         if ($this->nestedValidator === null) {
             return null;
         }
 
+        // traverse the VArray chain to get the final element type
+        if ($this->nestedValidator instanceof VArray) {
+            return $this->nestedValidator->getElementSwaggerType();
+        }
+
         return $this->nestedValidator::SWAGGER_TYPE;
     }
 
+    /**
+     * @return int Returns the defined depth of the array.
+     *  1 for arrays containing the final elements, 2 for arrays of arrays etc.
+     */
+    public function getArrayDepth(): int
+    {
+        if ($this->nestedValidator instanceof VArray) {
+            return $this->nestedValidator->getArrayDepth() + 1;
+        }
+
+        return 1;
+    }
+
+    /**
+     * @return ParameterConstraints Returns all parameter constrains of the bottommost element type that will be
+     *  written into the generated swagger document. Returns null if there are no constraints.
+     */
+    public function getConstraints(): ?ParameterConstraints
+    {
+        return $this->nestedValidator?->getConstraints();
+    }
+
     /**
      * Sets the strict flag for this validator and the element validator if present.
      * Expected to be changed by Attributes containing validators to change their behavior based on the Attribute type.

app/helpers/Swagger/AnnotationHelper.php

@@ -163,6 +163,11 @@ private static function extractStandardAnnotationParams(array $annotations, stri
 
                 // the array element type cannot be determined from standard @param annotations
                 $nestedArraySwaggerType = null;
+                // the actual depth of the array cannot be determined as well
+                $arrayDepth = null;
+                if ($swaggerType == "array") {
+                    $arrayDepth = 1;
+                }
 
                 $descriptor = new AnnotationParameterData(
                     $swaggerType,
@@ -172,6 +177,7 @@ private static function extractStandardAnnotationParams(array $annotations, stri
                     $isPathParam,
                     $nullable,
                     nestedArraySwaggerType: $nestedArraySwaggerType,
+                    arrayDepth: $arrayDepth,
                 );
                 $params[] = $descriptor;
             }

app/helpers/Swagger/AnnotationParameterData.php

@@ -18,6 +18,7 @@ class AnnotationParameterData
     public bool $nullable;
     public ?string $example;
     public ?string $nestedArraySwaggerType;
+    public ?int $arrayDepth;
     public ?array $nestedObjectParameterData;
     public ?ParameterConstraints $constraints;
 
@@ -30,6 +31,7 @@ public function __construct(
         bool $nullable,
         ?string $example = null,
         ?string $nestedArraySwaggerType = null,
+        ?int $arrayDepth = null,
         ?array $nestedObjectParameterData = null,
         ?ParameterConstraints $constraints = null,
     ) {
@@ -41,30 +43,54 @@ public function __construct(
         $this->nullable = $nullable;
         $this->example = $example;
         $this->nestedArraySwaggerType = $nestedArraySwaggerType;
+        $this->arrayDepth = $arrayDepth;
         $this->nestedObjectParameterData = $nestedObjectParameterData;
         $this->constraints = $constraints;
     }
 
     private function addArrayItemsIfArray(ParenthesesBuilder $container)
     {
-        ///TODO: nested constraints should be added here
         if ($this->swaggerType !== "array") {
             return;
         }
 
         $itemsHead = "@OA\\Items";
-        $items = new ParenthesesBuilder();
+        $layers = [];
+        for ($i = 0; $i < $this->arrayDepth; $i++) {
+            $items = new ParenthesesBuilder();
+
+            // add array time for all nested arrays
+            if ($i < $this->arrayDepth - 1) {
+                $items->addKeyValue("type", "array");
+                // handle bottommost elements
+            } else {
+                // add element type if present
+                if ($this->nestedArraySwaggerType !== null) {
+                    $items->addKeyValue("type", $this->nestedArraySwaggerType);
+                }
+
+                // add example value
+                if ($this->example != null) {
+                    $items->addKeyValue("example", $this->example);
+                }
+
+                // add constraints
+                $this->constraints?->addConstraints($items);
+            }
 
-        if ($this->nestedArraySwaggerType !== null) {
-            $items->addKeyValue("type", $this->nestedArraySwaggerType);
+            $layers[] = $items;
         }
 
-        // add example value
-        if ($this->example != null) {
-            $items->addKeyValue("example", $this->example);
+        // serialize the layers from the bottom up
+        $layers = array_reverse($layers);
+        $serialized_layer = $itemsHead . $layers[0]->toString();
+        for ($i = 1; $i < $this->arrayDepth; $i++) {
+            $layer = $layers[$i];
+            $layer->addValue($serialized_layer);
+            $serialized_layer = $itemsHead . $layer->toString();
         }
 
-        $container->addValue($itemsHead . $items->toString());
+        $container->addValue($serialized_layer);
     }
 
     private function addObjectParamsIfObject(ParenthesesBuilder $container)
@@ -133,8 +159,10 @@ public function toPropertyAnnotation(): string
             $body->addKeyValue("description", $this->description);
         }
 
-        // handle param constraints
-        $this->constraints?->addConstraints($body);
+        // handle param constraints (array constrains have to be added to the element, not the array)
+        if ($this->swaggerType !== "array") {
+            $this->constraints?->addConstraints($body);
+        }
 
         // handle arrays
         $this->addArrayItemsIfArray($body);