fix(doctrine): Handling of parameter description

src/OpenApi/Factory/OpenApiFactory.php

@@ -936,11 +936,16 @@ private function hasParameter(Operation $operation, Parameter $parameter): ?arra
 
     private function mergeParameter(Parameter $actual, Parameter $defined): Parameter
     {
+        // Handle description separately: only override if the new value is non-empty
+        $newDescription = $defined->getDescription();
+        if ('' !== $newDescription && $actual->getDescription() !== $newDescription) {
+            $actual = $actual->withDescription($newDescription);
+        }
+
         foreach (
             [
                 'name',
                 'in',
-                'description',
                 'required',
                 'deprecated',
                 'allowEmptyValue',

tests/Fixtures/TestBundle/Entity/ProductWithQueryParameter.php

@@ -30,6 +30,10 @@
                 'brand' => new QueryParameter(
                     filter: new ExactFilter(),
                 ),
+                'brandWithDescription' => new QueryParameter(
+                    filter: new ExactFilter(),
+                    description: 'Extra description about the filter',
+                ),
                 'search[:property]' => new QueryParameter(
                     filter: new PartialSearchFilter(),
                     properties: ['title', 'description']

tests/Functional/Parameters/DoctrineTest.php

@@ -302,7 +302,7 @@ private function loadProductFixtures(string $resourceClass): void
     }
 
     #[DataProvider('openApiParameterDocumentationProvider')]
-    public function testOpenApiParameterDocumentation(string $parameterName, bool $shouldHaveArrayNotation, string $expectedStyle, bool $expectedExplode, ?string $expectedSchemaType = null): void
+    public function testOpenApiParameterDocumentation(string $parameterName, bool $shouldHaveArrayNotation, string $expectedStyle, bool $expectedExplode, ?string $expectedSchemaType = null, string $expectedDescription = ''): void
     {
         if ($this->isMongoDB()) {
             $this->markTestSkipped('Not tested with mongodb.');
@@ -339,6 +339,9 @@ public function testOpenApiParameterDocumentation(string $parameterName, bool $s
             $this->assertSame($expectedSchemaType, $foundParameter['schema']['type'], \sprintf('Parameter schema type should be %s', $expectedSchemaType));
         }
 
+        if (isset($foundParameter['expectedDescription'])) {
+            $this->assertSame($expectedDescription, $foundParameter['description'] ?? '', \sprintf('Description should be %s', $expectedDescription));
+        }
         $this->assertSame($expectedStyle, $foundParameter['style'] ?? 'form', \sprintf('Style should be %s', $expectedStyle));
         $this->assertSame($expectedExplode, $foundParameter['explode'] ?? false, \sprintf('Explode should be %s', $expectedExplode ? 'true' : 'false'));
     }
@@ -353,6 +356,14 @@ public static function openApiParameterDocumentationProvider(): array
                 'expectedExplode' => true,
                 'expectedSchemaType' => 'string',
             ],
+            'default behavior with an extra description' => [
+                'parameterName' => 'brandWithDescription',
+                'shouldHaveArrayNotation' => true,
+                'expectedStyle' => 'deepObject',
+                'expectedExplode' => true,
+                'expectedSchemaType' => 'string',
+                'expectedDescription' => 'Extra description about the filter',
+            ],
             'explicit schema type string should not use array notation' => [
                 'parameterName' => 'exactBrand',
                 'shouldHaveArrayNotation' => false,