Allow unused tags to be kept (#1647)

src/Processors/AugmentTags.php

@@ -15,6 +15,25 @@
  */
 class AugmentTags implements ProcessorInterface
 {
+
+    /** @var array<string> */
+    protected $whitelist;
+
+    public function __construct(array $whitelist = [])
+    {
+        $this->whitelist = $whitelist;
+    }
+
+    /**
+     * Whitelist tags to keep even if not used. <code>*</code> may be used to keep all unused.
+     */
+    public function setWhitelist(array $whitelist): AugmentTags
+    {
+        $this->whitelist = $whitelist;
+
+        return $this;
+    }
+
     public function __invoke(Analysis $analysis)
     {
         /** @var OA\Operation[] $operations */
@@ -39,6 +58,7 @@ public function __invoke(Analysis $analysis)
             $analysis->openapi->tags = array_values($declaredTags);
         }
 
+        // Add a tag for each tag that is used in operations but not declared in the global tags
         if ($usedTagNames) {
             $declatedTagNames = array_keys($declaredTags);
             foreach ($usedTagNames as $tagName) {
@@ -48,8 +68,18 @@ public function __invoke(Analysis $analysis)
             }
         }
 
+        $this->removeUnusedTags($usedTagNames, $declaredTags, $analysis);
+    }
+
+    private function removeUnusedTags(array $usedTagNames, array $declaredTags, Analysis $analysis)
+    {
+        if (in_array('*', $this->whitelist)) {
+            return;
+        }
+
+        $tagsToKeep = array_merge($usedTagNames, $this->whitelist);
         foreach ($declaredTags as $tag) {
-            if (!in_array($tag->name, $usedTagNames)) {
+            if (!in_array($tag->name, $tagsToKeep)) {
                 if (false !== $index = array_search($tag, $analysis->openapi->tags, true)) {
                     $analysis->annotations->detach($tag);
                     unset($analysis->openapi->tags[$index]);

tests/Fixtures/UnusedTags.php

@@ -0,0 +1,32 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Tests\Fixtures;
+
+use OpenApi\Attributes as OAT;
+
+#[OAT\OpenApi(
+    info: new OAT\Info(
+        title: 'test',
+        description: 'test',
+        version: '2.0.0'
+    ),
+    tags: [
+        // definding tag 'other' globally with nice description
+        new OAT\Tag('other', 'Other description'),
+        // making a tag that has no operations referencing it, but we wish to keep it
+        new OAT\Tag('fancy', 'Fancy description'),
+        // making a tag that it not used, but we do not wish to keep
+        new OAT\Tag('notused', 'remove this one'),
+    ]
+)]
+class UnusedTags
+{
+    #[OAT\Get(path: '/other/', tags: ['other'], responses: [new OAT\Response(response: '200', description: 'success')])]
+    public function hello(): void
+    {
+    }
+}

tests/Processors/AugmentTagsTest.php

@@ -37,4 +37,42 @@ public function testDedupedAugmentTags(): void
 
         $this->assertCount(3, $analysis->openapi->tags, 'Expecting 3 unique tags');
     }
+
+    /**
+     * @requires PHP 8.1
+     */
+    public function testAllowUnusedTags(): void
+    {
+        $this->skipLegacy();
+
+        $analysis = $this->analysisFromFixtures(
+            ['UnusedTags.php'],
+            static::processors(),
+            null,
+            [
+                'augmentTags' => ['whitelist' => ['fancy']],
+            ]
+        );
+
+        $this->assertCount(2, $analysis->openapi->tags, 'Expecting fancy tag to be preserved');
+    }
+
+    /**
+     * @requires PHP 8.1
+     */
+    public function testAllowUnusedTagsWildcard(): void
+    {
+        $this->skipLegacy();
+
+        $analysis = $this->analysisFromFixtures(
+            ['UnusedTags.php'],
+            static::processors(),
+            null,
+            [
+                'augmentTags' => ['whitelist' => ['*']],
+            ]
+        );
+
+        $this->assertCount(3, $analysis->openapi->tags, 'Expecting all tags to be preserved');
+    }
 }