fix(openapi): ability to override description in response (#7412)

Author: VincentLanglet

src/OpenApi/Factory/OpenApiFactory.php

@@ -496,22 +496,26 @@ private function collectPaths(ApiResource $resource, ResourceMetadataCollection
         }
     }
 
-    private function buildOpenApiResponse(array $existingResponses, int|string $status, string $description, ?Operation $openapiOperation = null, ?HttpOperation $operation = null, ?array $responseMimeTypes = null, ?array $operationOutputSchemas = null, ?ResourceMetadataCollection $resourceMetadataCollection = null): Operation
+    /**
+     * @param array<Response> $existingResponses
+     *
+     * @return Operation
+     */
+    private function buildOpenApiResponse(array $existingResponses, int|string $status, string $description, Operation $openapiOperation, ?HttpOperation $operation = null, ?array $responseMimeTypes = null, ?array $operationOutputSchemas = null, ?ResourceMetadataCollection $resourceMetadataCollection = null): Operation
     {
         $noOutput = \is_array($operation?->getOutput()) && null === $operation->getOutput()['class'];
 
-        if (isset($existingResponses[$status])) {
-            return $openapiOperation;
-        }
-        $responseLinks = $responseContent = null;
-        if ($responseMimeTypes && $operationOutputSchemas && !$noOutput) {
-            $responseContent = $this->buildContent($responseMimeTypes, $operationOutputSchemas);
+        $response = $existingResponses[$status] ?? new Response($description);
+
+        if (!$response->getContent() && $responseMimeTypes && $operationOutputSchemas && !$noOutput) {
+            $response = $response->withContent($this->buildContent($responseMimeTypes, $operationOutputSchemas));
         }
-        if ($resourceMetadataCollection && $operation) {
-            $responseLinks = $this->getLinks($resourceMetadataCollection, $operation);
+
+        if (!$response->getLinks() && $resourceMetadataCollection && $operation) {
+            $response = $response->withLinks($this->getLinks($resourceMetadataCollection, $operation));
         }
 
-        return $openapiOperation->withResponse($status, new Response($description, $responseContent, null, $responseLinks));
+        return $openapiOperation->withResponse($status, $response);
     }
 
     /**

src/OpenApi/Tests/Factory/OpenApiFactoryTest.php

@@ -237,6 +237,7 @@ public function testInvoke(): void
                     responses: [
                         '200' => new OpenApiResponse(
                             description: 'Success',
+                            content: new \ArrayObject([]),
                         ),
                     ],
                 )),
@@ -1106,7 +1107,11 @@ public function testInvoke(): void
                         'link' => ['$ref' => '#/components/schemas/Dummy'],
                     ])
                 ),
-                '400' => new Response('Error'),
+                '400' => new Response(
+                    'Error',
+                    content: new \ArrayObject(['application/problem+json' => new MediaType(schema: new \ArrayObject(['$ref' => '#/components/schemas/Error']))]),
+                    links: new \ArrayObject(['getDummyItem' => new Model\Link('getDummyItem', new \ArrayObject(['id' => '$response.body#/id']), null, 'This is a dummy')])
+                ),
                 '422' => new Response(
                     'Unprocessable entity',
                     content: new \ArrayObject(['application/problem+json' => new MediaType(schema: new \ArrayObject(['$ref' => '#/components/schemas/Error']))]),
@@ -1150,7 +1155,11 @@ public function testInvoke(): void
                         'link' => ['$ref' => '#/components/schemas/Dummy'],
                     ])
                 ),
-                '400' => new Response('Error'),
+                '400' => new Response(
+                    'Error',
+                    content: new \ArrayObject(['application/problem+json' => new MediaType(schema: new \ArrayObject(['$ref' => '#/components/schemas/Error']))]),
+                    links: new \ArrayObject(['getDummyItem' => new Model\Link('getDummyItem', new \ArrayObject(['id' => '$response.body#/id']), null, 'This is a dummy')])
+                ),
                 '422' => new Response(
                     'Unprocessable entity',
                     content: new \ArrayObject(['application/problem+json' => new MediaType(schema: new \ArrayObject(['$ref' => '#/components/schemas/Error']))]),
@@ -1177,7 +1186,8 @@ public function testInvoke(): void
             ['Dummy'],
             [
                 '200' => new Response(
-                    'Success'
+                    'Success',
+                    content: new \ArrayObject([]),
                 ),
             ],
             'Retrieves the collection of Dummy resources.',