added swagger generator support for format classes

ReCodEx · Mar 2, 2025 · 73752f0 · 73752f0
1 parent 18501e1
commit 73752f0
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 22 deletions.
diff --git a/app/helpers/MetaFormats/RequestParamData.php b/app/helpers/MetaFormats/RequestParamData.php
@@ -129,6 +129,16 @@ public function toAnnotationParameterData()
             $exampleValue = $this->validators[0]->getExampleValue();
         }
 
+        // add nested parameter data if this is an object
+        $format = $this->getFormatName();
+        $nestedObjectParameterData = null;
+        if ($format !== null) {
+            $nestedRequestParmData = FormatCache::getFieldDefinitions($format);
+            $nestedObjectParameterData = array_map(function (RequestParamData $data) {
+                return $data->toAnnotationParameterData();
+            }, $nestedRequestParmData);
+        }
+
         return new AnnotationParameterData(
             $swaggerType,
             $this->name,
@@ -138,6 +148,7 @@ public function toAnnotationParameterData()
             $this->nullable,
             $exampleValue,
             $nestedArraySwaggerType,
+            $nestedObjectParameterData,
         );
     }
 }
diff --git a/app/helpers/MetaFormats/Validators/VFormat.php b/app/helpers/MetaFormats/Validators/VFormat.php
@@ -25,12 +25,6 @@ public function __construct(string $format)
         }
     }
 
-    public function getExampleValue()
-    {
-        ///TODO
-        return "0";
-    }
-
     public function validate(mixed $value)
     {
         // fine-grained checking is done in the properties

diff --git a/app/helpers/Swagger/AnnotationHelper.php b/app/helpers/Swagger/AnnotationHelper.php
@@ -3,6 +3,7 @@
 namespace App\Helpers\Swagger;
 
 use App\Exceptions\InvalidArgumentException;
+use App\Helpers\MetaFormats\FormatCache;
 use App\Helpers\MetaFormats\MetaFormatHelper;
 use App\V1Module\Router\MethodRoute;
 use App\V1Module\RouterFactory;
@@ -339,7 +340,17 @@ public static function extractAttributeData(string $className, string $methodNam
         $methodAnnotations = self::getMethodAnnotations($className, $methodName);
 
         $httpMethod = self::extractAnnotationHttpMethod($methodAnnotations);
-        $attributeData = MetaFormatHelper::extractRequestParamData(self::getMethod($className, $methodName));
+        $reflectionMethod = self::getMethod($className, $methodName);
+
+        $format = MetaFormatHelper::extractFormatFromAttribute($reflectionMethod);
+        // if the endpoint is linked to a format, use the format class
+        if ($format !== null) {
+            $attributeData = FormatCache::getFieldDefinitions($format);
+        // otherwise use loose param attributes
+        } else {
+            $attributeData = MetaFormatHelper::extractRequestParamData($reflectionMethod);
+        }
+
         $params = array_map(function ($data) {
             return $data->toAnnotationParameterData();
         }, $attributeData);

diff --git a/app/helpers/Swagger/AnnotationParameterData.php b/app/helpers/Swagger/AnnotationParameterData.php
@@ -18,6 +18,7 @@ class AnnotationParameterData
     public bool $nullable;
     public ?string $example;
     public ?string $nestedArraySwaggerType;
+    public ?array $nestedObjectParameterData;
 
     public function __construct(
         string $swaggerType,
@@ -28,6 +29,7 @@ public function __construct(
         bool $nullable,
         string $example = null,
         string $nestedArraySwaggerType = null,
+        ?array $nestedObjectParameterData = null,
     ) {
         $this->swaggerType = $swaggerType;
         $this->name = $name;
@@ -37,24 +39,39 @@ public function __construct(
         $this->nullable = $nullable;
         $this->example = $example;
         $this->nestedArraySwaggerType = $nestedArraySwaggerType;
+        $this->nestedObjectParameterData = $nestedObjectParameterData;
     }
 
-    private function addArrayItemsIfArray(string $swaggerType, ParenthesesBuilder $container)
+    private function addArrayItemsIfArray(ParenthesesBuilder $container)
     {
-        if ($swaggerType === "array") {
-            $itemsHead = "@OA\\Items";
-            $items = new ParenthesesBuilder();
+        if ($this->swaggerType !== "array") {
+            return;
+        }
 
-            if ($this->nestedArraySwaggerType !== null) {
-                $items->addKeyValue("type", $this->nestedArraySwaggerType);
-            }
+        $itemsHead = "@OA\\Items";
+        $items = new ParenthesesBuilder();
 
-            // add example value
-            if ($this->example != null) {
-                $items->addKeyValue("example", $this->example);
-            }
+        if ($this->nestedArraySwaggerType !== null) {
+            $items->addKeyValue("type", $this->nestedArraySwaggerType);
+        }
+
+        // add example value
+        if ($this->example != null) {
+            $items->addKeyValue("example", $this->example);
+        }
+
+        $container->addValue($itemsHead . $items->toString());
+    }
+
+    private function addObjectParamsIfObject(ParenthesesBuilder $container)
+    {
+        if ($this->nestedObjectParameterData === null) {
+            return;
+        }
 
-            $container->addValue($itemsHead . $items->toString());
+        foreach ($this->nestedObjectParameterData as $paramData) {
+            $annotation = $paramData->toPropertyAnnotation();
+            $container->addValue($annotation);
         }
     }
 
@@ -68,7 +85,7 @@ private function generateSchemaAnnotation(): string
         $body = new ParenthesesBuilder();
 
         $body->addKeyValue("type", $this->swaggerType);
-        $this->addArrayItemsIfArray($this->swaggerType, $body);
+        $this->addArrayItemsIfArray($body);
 
         return $head . $body->toString();
     }
@@ -112,10 +129,13 @@ public function toPropertyAnnotation(): string
         }
 
         // handle arrays
-        $this->addArrayItemsIfArray($this->swaggerType, $body);
+        $this->addArrayItemsIfArray($body);
+
+        // handle objects
+        $this->addObjectParamsIfObject($body);
 
         // add example value
-        if ($this->swaggerType !== "array") {
+        if ($this->swaggerType !== "array" && $this->swaggerType !== "object") {
             if ($this->example != null) {
                 $body->addKeyValue("example", $this->example);
             }