From a7fe3b19cc1132fadf66dc4403d520edc37ca324 Mon Sep 17 00:00:00 2001 From: Vincent Langlet Date: Wed, 7 Jan 2026 15:07:51 +0100 Subject: [PATCH 1/2] Keep Parameter description when generating OpenApiParameter --- src/Doctrine/Common/Filter/OpenApiFilterTrait.php | 14 ++++++++++++-- .../Entity/ProductWithQueryParameter.php | 4 ++++ tests/Functional/Parameters/DoctrineTest.php | 11 ++++++++++- 3 files changed, 26 insertions(+), 3 deletions(-) diff --git a/src/Doctrine/Common/Filter/OpenApiFilterTrait.php b/src/Doctrine/Common/Filter/OpenApiFilterTrait.php index 5371451f10..f82616ee35 100644 --- a/src/Doctrine/Common/Filter/OpenApiFilterTrait.php +++ b/src/Doctrine/Common/Filter/OpenApiFilterTrait.php @@ -33,9 +33,19 @@ public function getOpenApiParameters(Parameter $parameter): OpenApiParameter|arr $hasNonArraySchema = null !== $schema && !$isArraySchema; if ($hasNonArraySchema || false === $castToArray) { - return new OpenApiParameter(name: $parameter->getKey(), in: 'query'); + return new OpenApiParameter( + name: $parameter->getKey(), + in: 'query', + description: $parameter->getDescription() ?? '', + ); } - return new OpenApiParameter(name: $parameter->getKey().'[]', in: 'query', style: 'deepObject', explode: true); + return new OpenApiParameter( + name: $parameter->getKey().'[]', + in: 'query', + description: $parameter->getDescription() ?? '', + style: 'deepObject', + explode: true, + ); } } 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..97f61fff83 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,7 @@ public function testOpenApiParameterDocumentation(string $parameterName, bool $s $this->assertSame($expectedSchemaType, $foundParameter['schema']['type'], \sprintf('Parameter schema type should be %s', $expectedSchemaType)); } + $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 +354,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, From e799de2511463e98fb252f6fd96c19f91527a030 Mon Sep 17 00:00:00 2001 From: soyuka Date: Thu, 8 Jan 2026 15:24:29 +0100 Subject: [PATCH 2/2] fix into openapi instead --- src/Doctrine/Common/Filter/OpenApiFilterTrait.php | 14 ++------------ src/OpenApi/Factory/OpenApiFactory.php | 7 ++++++- tests/Functional/Parameters/DoctrineTest.php | 4 +++- 3 files changed, 11 insertions(+), 14 deletions(-) diff --git a/src/Doctrine/Common/Filter/OpenApiFilterTrait.php b/src/Doctrine/Common/Filter/OpenApiFilterTrait.php index f82616ee35..5371451f10 100644 --- a/src/Doctrine/Common/Filter/OpenApiFilterTrait.php +++ b/src/Doctrine/Common/Filter/OpenApiFilterTrait.php @@ -33,19 +33,9 @@ public function getOpenApiParameters(Parameter $parameter): OpenApiParameter|arr $hasNonArraySchema = null !== $schema && !$isArraySchema; if ($hasNonArraySchema || false === $castToArray) { - return new OpenApiParameter( - name: $parameter->getKey(), - in: 'query', - description: $parameter->getDescription() ?? '', - ); + return new OpenApiParameter(name: $parameter->getKey(), in: 'query'); } - return new OpenApiParameter( - name: $parameter->getKey().'[]', - in: 'query', - description: $parameter->getDescription() ?? '', - style: 'deepObject', - explode: true, - ); + return new OpenApiParameter(name: $parameter->getKey().'[]', in: 'query', style: 'deepObject', explode: true); } } 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/Functional/Parameters/DoctrineTest.php b/tests/Functional/Parameters/DoctrineTest.php index 97f61fff83..c74803d2e5 100644 --- a/tests/Functional/Parameters/DoctrineTest.php +++ b/tests/Functional/Parameters/DoctrineTest.php @@ -339,7 +339,9 @@ public function testOpenApiParameterDocumentation(string $parameterName, bool $s $this->assertSame($expectedSchemaType, $foundParameter['schema']['type'], \sprintf('Parameter schema type should be %s', $expectedSchemaType)); } - $this->assertSame($expectedDescription, $foundParameter['description'] ?? '', \sprintf('Description should be %s', $expectedDescription)); + 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')); }