fix(openapi): dedup legacy filter deprecations

getFiltersParameters() looped every filter description entry and
re-emitted the same swagger/openapi deprecation per parameter, so a
filter exposing N params warned N times per doc generation. Guard the
two triggers with a per-invocation $warned set keyed by filter +
shortName so each fires at most once per generation.

Establishes the F7 dedup convention (natural boundaries + local guard,
no global static state) that the upcoming #[ApiFilter] (F5) and
Operation::$filters (F6) runtime deprecations reuse.

Author: soyuka

src/OpenApi/Factory/OpenApiFactory.php

@@ -702,27 +702,33 @@ private function getFiltersParameters(CollectionOperationInterface|HttpOperation
         $resourceFilters = $operation->getFilters();
         $entityClass = $this->getStateOptionsClass($operation, $operation->getClass());
 
+        // Collapse identical filter deprecations to one warning per (filter, shortName) per
+        // generation: a filter exposing N parameters must not emit the same message N times.
+        $warned = [];
         foreach ($resourceFilters ?? [] as $filterId) {
             if (!$this->filterLocator->has($filterId)) {
                 continue;
             }
 
             $filter = $this->filterLocator->get($filterId);
             foreach ($filter->getDescription($entityClass) as $name => $description) {
-                $parameters[] = $this->getFilterParameter($name, $description, $operation->getShortName(), $filterId);
+                $parameters[] = $this->getFilterParameter($name, $description, $operation->getShortName(), $filterId, $warned);
             }
         }
 
         return $parameters;
     }
 
     /**
-     * @param array<string, mixed> $description
+     * @param array<string, mixed>               $description
+     * @param array<string, array<string, bool>> $warned
      */
-    private function getFilterParameter(string $name, array $description, string $shortName, string $filter): Parameter
+    private function getFilterParameter(string $name, array $description, string $shortName, string $filter, array &$warned = []): Parameter
     {
-        if (isset($description['swagger'])) {
+        $warnKey = $filter.'::'.$shortName;
+        if (isset($description['swagger']) && !isset($warned[$warnKey]['swagger'])) {
             trigger_deprecation('api-platform/core', '4.0', \sprintf('Using the "swagger" field of the %s::getDescription() (%s) is deprecated.', $filter, $shortName));
+            $warned[$warnKey]['swagger'] = true;
         }
 
         if (!isset($description['openapi']) || $description['openapi'] instanceof Parameter) {
@@ -771,7 +777,10 @@ private function getFilterParameter(string $name, array $description, string $sh
             return $parameter->withSchema($schema);
         }
 
-        trigger_deprecation('api-platform/core', '4.0', \sprintf('Not using "%s" on the "openapi" field of the %s::getDescription() (%s) is deprecated.', Parameter::class, $filter, $shortName));
+        if (!isset($warned[$warnKey]['openapi'])) {
+            trigger_deprecation('api-platform/core', '4.0', \sprintf('Not using "%s" on the "openapi" field of the %s::getDescription() (%s) is deprecated.', Parameter::class, $filter, $shortName));
+            $warned[$warnKey]['openapi'] = true;
+        }
 
         $schema = $description['schema'] ?? null;
 

src/OpenApi/Tests/Factory/OpenApiFactoryTest.php

@@ -1498,4 +1498,81 @@ public function testMetadataParameterInOpenApiOperationParametersThrows(): void
 
         $factory->__invoke();
     }
+
+    public function testLegacyFilterDeprecationFiresOncePerFilterAndShortName(): void
+    {
+        $resourceNameCollectionFactory = $this->createMock(ResourceNameCollectionFactoryInterface::class);
+        $resourceCollectionMetadataFactory = $this->createMock(ResourceMetadataCollectionFactoryInterface::class);
+        $propertyNameCollectionFactory = $this->createMock(PropertyNameCollectionFactoryInterface::class);
+        $propertyMetadataFactory = $this->createMock(PropertyMetadataFactoryInterface::class);
+        $definitionNameFactory = new DefinitionNameFactory([]);
+
+        $resourceCollectionMetadata = new ResourceMetadataCollection(Dummy::class, [(new ApiResource(operations: [
+            (new GetCollection())
+                ->withClass(Dummy::class)
+                ->withShortName('Dummy')
+                ->withName('api_dummies_get_collection')
+                ->withUriTemplate('/dummies')
+                ->withFilters(['legacy_filter']),
+        ]))->withClass(Dummy::class)]);
+
+        $resourceCollectionMetadataFactory
+            ->method('create')
+            ->willReturnCallback(static fn (string $resourceClass): ResourceMetadataCollection => match ($resourceClass) {
+                Dummy::class => $resourceCollectionMetadata,
+                default => new ResourceMetadataCollection($resourceClass, []),
+            });
+
+        $resourceNameCollectionFactory->method('create')->willReturn(new ResourceNameCollection([Dummy::class]));
+        $propertyNameCollectionFactory->method('create')->willReturn(new PropertyNameCollection([]));
+
+        // A legacy filter exposing several parameters, each carrying the deprecated "swagger" field.
+        $filter = new DummyFilter([
+            'name' => ['property' => 'name', 'type' => 'string', 'required' => false, 'swagger' => ['type' => 'string']],
+            'foo' => ['property' => 'foo', 'type' => 'string', 'required' => false, 'swagger' => ['type' => 'string']],
+            'bar' => ['property' => 'bar', 'type' => 'string', 'required' => false, 'swagger' => ['type' => 'string']],
+        ]);
+
+        $filterLocator = $this->createMock(ContainerInterface::class);
+        $filterLocator->method('has')->willReturnCallback(static fn (string $id): bool => 'legacy_filter' === $id);
+        $filterLocator->method('get')->willReturn($filter);
+
+        $schemaFactory = new SchemaFactory(
+            resourceMetadataFactory: $resourceCollectionMetadataFactory,
+            propertyNameCollectionFactory: $propertyNameCollectionFactory,
+            propertyMetadataFactory: $propertyMetadataFactory,
+            nameConverter: new CamelCaseToSnakeCaseNameConverter(),
+            definitionNameFactory: $definitionNameFactory,
+        );
+
+        $factory = new OpenApiFactory(
+            $resourceNameCollectionFactory,
+            $resourceCollectionMetadataFactory,
+            $propertyNameCollectionFactory,
+            $propertyMetadataFactory,
+            $schemaFactory,
+            $filterLocator,
+            [],
+            new Options('Test API', 'This is a test API.', '1.2.3'),
+            new PaginationOptions(),
+            null,
+            ['json' => ['application/problem+json']]
+        );
+
+        $deprecations = [];
+        set_error_handler(static function (int $type, string $message) use (&$deprecations): bool {
+            $deprecations[] = $message;
+
+            return true;
+        }, \E_USER_DEPRECATED);
+
+        try {
+            $factory->__invoke();
+        } finally {
+            restore_error_handler();
+        }
+
+        $swaggerDeprecations = array_filter($deprecations, static fn (string $m): bool => str_contains($m, 'Using the "swagger" field'));
+        $this->assertCount(1, $swaggerDeprecations, 'The "swagger" deprecation must fire once per filter and short name, not once per filter parameter.');
+    }
 }