Use Analysis::removeAnnotation() in MergeControllerDefaults; deprecate clearUnusedPaths

src/OpenApiBuilder.php

@@ -65,7 +65,7 @@ public function tagsToMatch($tags): OpenApiBuilder
     }
 
     /**
-     * Enable/disable recursive cleanup of unused paths and their nested annotations.
+     * @deprecated will be removed in the next major version
      */
     public function clearUnusedPaths(bool $enabled = true): OpenApiBuilder
     {

src/Processors/MergeControllerDefaults.php

@@ -20,7 +20,7 @@ public function __invoke(Analysis $analysis): void
         foreach ($operations as $operation) {
             $chain = $this->resolveControllerChain($operation->_context, $controllerMap, $analysis);
             if ($chain !== []) {
-                $this->applyChain($operation, $chain);
+                $this->applyChain($analysis, $operation, $chain);
             }
         }
 
@@ -95,7 +95,7 @@ protected function resolveControllerChain(?Context $operationContext, array $con
     /**
      * @param OAX\Controller[] $chain
      */
-    protected function applyChain(OA\Operation $operation, array $chain): void
+    protected function applyChain(Analysis $analysis, OA\Operation $operation, array $chain): void
     {
         $mergedPrefix = '';
         $mergedTags = [];
@@ -133,9 +133,9 @@ protected function applyChain(OA\Operation $operation, array $chain): void
 
         $this->applyPrefix($operation, $mergedPrefix);
         $this->applyTags($operation, $mergedTags);
-        $this->applyResponses($operation, $mergedResponses);
-        $this->applyHeaders($operation, $mergedHeaders);
-        $this->applyMiddlewares($operation, $mergedMiddlewares);
+        $this->applyResponses($analysis, $operation, $mergedResponses);
+        $this->applyHeaders($analysis, $operation, $mergedHeaders);
+        $this->applyMiddlewares($analysis, $operation, $mergedMiddlewares);
     }
 
     protected function applyPrefix(OA\Operation $operation, string $mergedPrefix): void
@@ -162,7 +162,7 @@ protected function applyTags(OA\Operation $operation, array $mergedTags): void
     /**
      * @param array<string|int, OA\Response> $mergedResponses
      */
-    protected function applyResponses(OA\Operation $operation, array $mergedResponses): void
+    protected function applyResponses(Analysis $analysis, OA\Operation $operation, array $mergedResponses): void
     {
         if ($mergedResponses !== []) {
             $operation->merge(array_values($mergedResponses), true);
@@ -172,7 +172,7 @@ protected function applyResponses(OA\Operation $operation, array $mergedResponse
     /**
      * @param array<string, OA\Header> $mergedHeaders
      */
-    protected function applyHeaders(OA\Operation $operation, array $mergedHeaders): void
+    protected function applyHeaders(Analysis $analysis, OA\Operation $operation, array $mergedHeaders): void
     {
         if ($mergedHeaders && !Generator::isDefault($operation->responses)) {
             foreach ($operation->responses as $response) {
@@ -211,7 +211,7 @@ protected function collectMiddlewares(mixed $attachables, array $mergedMiddlewar
     /**
      * @param array<string, OAX\Middleware> $mergedMiddlewares
      */
-    protected function applyMiddlewares(OA\Operation $operation, array $mergedMiddlewares): void
+    protected function applyMiddlewares(Analysis $analysis, OA\Operation $operation, array $mergedMiddlewares): void
     {
         if ($mergedMiddlewares === []) {
             return;
@@ -237,7 +237,12 @@ protected function clearMerged(Analysis $analysis, $annotations): void
         $annotations = is_array($annotations) ? $annotations : [$annotations];
 
         foreach ($annotations as $annotation) {
-            $analysis->annotations->offsetUnset($annotation);
+            /* @phpstan-ignore function.alreadyNarrowedType */
+            if (method_exists($analysis, 'removeAnnotation')) {
+                $analysis->removeAnnotation($annotation);
+            } else {
+                $analysis->annotations->offsetUnset($annotation);
+            }
         }
     }
 }