response formats now propagate to the swagger

Author: eceltov

app/helpers/MetaFormats/Attributes/ResponseFormat.php

@@ -7,13 +7,15 @@
 /**
  * Attribute defining response format on endpoints.
  */
-#[Attribute]
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
 class ResponseFormat
 {
-    public string $class;
+    public readonly string $format;
+    public readonly int $statusCode;
 
-    public function __construct(string $class)
+    public function __construct(string $format, int $statusCode = 200)
     {
-        $this->class = $class;
+        $this->format = $format;
+        $this->statusCode = $statusCode;
     }
 }

app/helpers/MetaFormats/MetaFormatHelper.php

@@ -44,21 +44,21 @@ public static function extractFormatFromAttribute(
     }
 
     /**
-     * Checks whether an entity contains a ResponseFormat attribute and extracts the format if so.
+     * Checks whether an entity contains ResponseFormat attributes and returns them.
      * @param \ReflectionClass|\ReflectionProperty|\ReflectionMethod $reflectionObject A reflection
      * object of the entity.
-     * @return ?string Returns the format or null if no ResponseFormat attribute was present.
+     * @return array Returns an array of attribute instances.
      */
     public static function extractResponseFormatFromAttribute(
         ReflectionClass | ReflectionProperty | ReflectionMethod $reflectionObject
-    ): ?string {
+    ): array {
         $formatAttributes = $reflectionObject->getAttributes(ResponseFormat::class);
-        if (count($formatAttributes) === 0) {
-            return null;
+        $instances = [];
+        foreach ($formatAttributes as $formatAttribute) {
+            $instances[] = $formatAttribute->newInstance();
         }
 
-        $formatAttribute = $formatAttributes[0]->newInstance();
-        return $formatAttribute->class;
+        return $instances;
     }
 
     /**

app/helpers/Swagger/AnnotationData.php

@@ -31,6 +31,10 @@ class AnnotationData
      * @var AnnotationParameterData[]
      */
     public array $fileParams;
+    /**
+     * @var array<int, array<AnnotationParameterData>>
+     */
+    public array $statusToParamsMap;
     public ?string $endpointDescription;
 
     public function __construct(
@@ -41,8 +45,8 @@ public function __construct(
         array $queryParams,
         array $bodyParams,
         array $fileParams,
+        array $statusToParamsMap,
         ?string $endpointDescription = null,
-        ?array $responseParams = null,
     ) {
         $this->className = $className;
         $this->methodName = $methodName;
@@ -51,8 +55,8 @@ public function __construct(
         $this->queryParams = $queryParams;
         $this->bodyParams = $bodyParams;
         $this->fileParams = $fileParams;
+        $this->statusToParamsMap = $statusToParamsMap;
         $this->endpointDescription = $endpointDescription;
-        $this->responseParams = $responseParams;
     }
 
     public function getAllParams(): array
@@ -231,9 +235,21 @@ public function toSwaggerAnnotations(string $route)
             $body->addValue($bodyProperties);
         }
 
-        ///TODO: A placeholder for the response type. This has to be replaced with the autogenerated meta-view
-        /// response data structure in the future.
-        $body->addValue('@OA\Response(response="200",description="The data")');
+        // generate responses
+        foreach ($this->statusToParamsMap as $statusCode => $responseParams) {
+            $responseSchema = $this->serializeBodyParams(
+                "application/json",
+                $responseParams
+            );
+
+            $body->addValue('@OA\Response(response="' . $statusCode . '", ' . $responseSchema . ' )');
+        }
+
+        // add a placeholder response if none present
+        if (count($this->statusToParamsMap) === 0) {
+            $body->addValue('@OA\Response(response="200",description="Placeholder response")');
+        }
+
         return $httpMethodAnnotation . $body->toString();
     }
 }

app/helpers/Swagger/AnnotationHelper.php

@@ -2,6 +2,7 @@
 
 namespace App\Helpers\Swagger;
 
+use App\Exceptions\InternalServerException;
 use App\Helpers\MetaFormats\FormatCache;
 use App\Helpers\MetaFormats\MetaFormatHelper;
 use App\V1Module\Router\MethodRoute;
@@ -289,8 +290,8 @@ private static function annotationParameterDataToAnnotationData(
         string $methodName,
         HttpMethods $httpMethod,
         array $params,
+        array $statusToParamsMap,
         ?string $description,
-        ?array $responseParams = null,
     ): AnnotationData {
         $pathParams = [];
         $queryParams = [];
@@ -319,8 +320,8 @@ private static function annotationParameterDataToAnnotationData(
             $queryParams,
             $bodyParams,
             $fileParams,
+            $statusToParamsMap,
             $description,
-            $responseParams,
         );
     }
 
@@ -350,6 +351,7 @@ public static function extractStandardAnnotationData(
             $methodName,
             $httpMethod,
             $params,
+            [], // there are no reponse params defined in the old annotations
             $description
         );
     }
@@ -379,14 +381,23 @@ public static function extractAttributeData(string $className, string $methodNam
             $attributeData = array_merge($attributeData, FormatCache::getFieldDefinitions($format));
         }
 
-        // if the endpoint uses a response format, extract its parameters
-        $responseFormat = MetaFormatHelper::extractResponseFormatFromAttribute($reflectionMethod);
-        $responseParams = null;
-        if ($responseFormat !== null) {
-            $responseFieldDefinitions = FormatCache::getFieldDefinitions($responseFormat);
+        // if the endpoint uses response formats, extract their parameters
+        $responseAttributes = MetaFormatHelper::extractResponseFormatFromAttribute($reflectionMethod);
+        $statusToParamsMap = [];
+        foreach ($responseAttributes as $responseAttribute) {
+            $responseFieldDefinitions = FormatCache::getFieldDefinitions($responseAttribute->format);
             $responseParams = array_map(function ($data) {
                 return $data->toAnnotationParameterData();
             }, $responseFieldDefinitions);
+
+            // check if all response status codes are unique
+            if (array_key_exists($responseAttribute->statusCode, $statusToParamsMap)) {
+                throw new InternalServerException(
+                    "The method " . $reflectionMethod->name . " contains duplicate response codes."
+                );
+            }
+
+            $statusToParamsMap[$responseAttribute->statusCode] = $responseParams;
         }
 
         $params = array_map(function ($data) {
@@ -399,8 +410,8 @@ public static function extractAttributeData(string $className, string $methodNam
             $methodName,
             $httpMethod,
             $params,
+            $statusToParamsMap,
             $description,
-            $responseParams,
         );
     }