From 6c6ef6f15bd9b2aec6257d86a597f9c909e36809 Mon Sep 17 00:00:00 2001
From: Vincent Langlet <vincentlanglet@hotmail.fr>
Date: Thu, 25 Sep 2025 19:48:33 +0200
Subject: [PATCH] Allow to override description in response

---
 src/OpenApi/Factory/OpenApiFactory.php        | 24 +++++++++++--------
 .../Tests/Factory/OpenApiFactoryTest.php      | 16 ++++++++++---
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/src/OpenApi/Factory/OpenApiFactory.php b/src/OpenApi/Factory/OpenApiFactory.php
index abed0cf19c..15828a2d78 100644
--- a/src/OpenApi/Factory/OpenApiFactory.php
+++ b/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);
     }
 
     /**
diff --git a/src/OpenApi/Tests/Factory/OpenApiFactoryTest.php b/src/OpenApi/Tests/Factory/OpenApiFactoryTest.php
index c32286bc11..71e9c0c27f 100644
--- a/src/OpenApi/Tests/Factory/OpenApiFactoryTest.php
+++ b/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.',