diff --git a/src/OpenApi/Factory/OpenApiFactory.php b/src/OpenApi/Factory/OpenApiFactory.php index 272feae527..3759fa4266 100644 --- a/src/OpenApi/Factory/OpenApiFactory.php +++ b/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', diff --git a/tests/Fixtures/TestBundle/Entity/ProductWithQueryParameter.php b/tests/Fixtures/TestBundle/Entity/ProductWithQueryParameter.php index dae67eebe9..dbe6391361 100644 --- a/tests/Fixtures/TestBundle/Entity/ProductWithQueryParameter.php +++ b/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'] diff --git a/tests/Functional/Parameters/DoctrineTest.php b/tests/Functional/Parameters/DoctrineTest.php index 5e21ec429b..c74803d2e5 100644 --- a/tests/Functional/Parameters/DoctrineTest.php +++ b/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,