From a4116d139d083a40eda241cdec0b7ad68630fa4e Mon Sep 17 00:00:00 2001
From: Paul Johnston <paul-johnston@zencontrol.com>
Date: Tue, 27 Aug 2024 16:42:00 +1000
Subject: [PATCH 1/5] allow unused tags to be kept

---
 src/Processors/AugmentTags.php       | 21 +++++++++++++++++-
 tests/Fixtures/UnusedTags.php        | 32 ++++++++++++++++++++++++++++
 tests/Processors/AugmentTagsTest.php | 19 +++++++++++++++++
 3 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 tests/Fixtures/UnusedTags.php

diff --git a/src/Processors/AugmentTags.php b/src/Processors/AugmentTags.php
index 171b6387..8be6b00c 100644
--- a/src/Processors/AugmentTags.php
+++ b/src/Processors/AugmentTags.php
@@ -15,6 +15,22 @@
  */
 class AugmentTags implements ProcessorInterface
 {
+
+    /** @var array<string>  */
+    protected array $unusedTagsToKeepWhitelist = [];
+
+    public function __construct(array $unusedTagsToKeepWhitelist = [])
+    {
+        $this->unusedTagsToKeepWhitelist = $unusedTagsToKeepWhitelist;
+    }
+
+    public function setUnusedTagsToKeepWhitelist(array $unusedTagsToKeepWhitelist): AugmentTags
+    {
+        $this->unusedTagsToKeepWhitelist = $unusedTagsToKeepWhitelist;
+
+        return $this;
+    }
+
     public function __invoke(Analysis $analysis)
     {
         /** @var OA\Operation[] $operations */
@@ -39,6 +55,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 +65,10 @@ public function __invoke(Analysis $analysis)
             }
         }
 
+        // remove tags that we don't want to keep (defaults to all unused tags)
+        $tagsToKeep = array_merge($usedTagNames, $this->unusedTagsToKeepWhitelist);
         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]);
diff --git a/tests/Fixtures/UnusedTags.php b/tests/Fixtures/UnusedTags.php
new file mode 100644
index 00000000..1a35293c
--- /dev/null
+++ b/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
+    {
+    }
+}
diff --git a/tests/Processors/AugmentTagsTest.php b/tests/Processors/AugmentTagsTest.php
index 0e419e0f..a34f4127 100644
--- a/tests/Processors/AugmentTagsTest.php
+++ b/tests/Processors/AugmentTagsTest.php
@@ -37,4 +37,23 @@ 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' => ['unusedTagsToKeepWhitelist' => ['fancy']]
+            ]
+        );
+
+        $this->assertCount(2, $analysis->openapi->tags, 'Expecting 3 unique tags');
+    }
 }

From 6e2e57311aeb7f2c7cf2deb7390348abedadc06c Mon Sep 17 00:00:00 2001
From: Paul Johnston <paul-johnston@zencontrol.com>
Date: Tue, 27 Aug 2024 16:52:08 +1000
Subject: [PATCH 2/5] fix test comment

---
 tests/Processors/AugmentTagsTest.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/Processors/AugmentTagsTest.php b/tests/Processors/AugmentTagsTest.php
index a34f4127..2a8c178c 100644
--- a/tests/Processors/AugmentTagsTest.php
+++ b/tests/Processors/AugmentTagsTest.php
@@ -54,6 +54,6 @@ public function testAllowUnusedTags(): void
             ]
         );
 
-        $this->assertCount(2, $analysis->openapi->tags, 'Expecting 3 unique tags');
+        $this->assertCount(2, $analysis->openapi->tags, 'Expecting fancy tag to be preserved');
     }
 }

From 19d4cceab76a25c678789db901cd148d41a0d47f Mon Sep 17 00:00:00 2001
From: Paul Johnston <paul-johnston@zencontrol.com>
Date: Wed, 28 Aug 2024 09:42:15 +1000
Subject: [PATCH 3/5] remove typed property to be compatible with php7.2

---
 src/Processors/AugmentTags.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Processors/AugmentTags.php b/src/Processors/AugmentTags.php
index 8be6b00c..d888f94e 100644
--- a/src/Processors/AugmentTags.php
+++ b/src/Processors/AugmentTags.php
@@ -17,7 +17,7 @@ class AugmentTags implements ProcessorInterface
 {
 
     /** @var array<string>  */
-    protected array $unusedTagsToKeepWhitelist = [];
+    protected $unusedTagsToKeepWhitelist = [];
 
     public function __construct(array $unusedTagsToKeepWhitelist = [])
     {

From 0904ea0f9c30c8025d92075705e63a5f825ee07f Mon Sep 17 00:00:00 2001
From: Paul Johnston <paul-johnston@zencontrol.com>
Date: Wed, 28 Aug 2024 09:47:56 +1000
Subject: [PATCH 4/5] fix new code style errors

---
 src/Processors/AugmentTags.php       | 2 +-
 tests/Processors/AugmentTagsTest.php | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/Processors/AugmentTags.php b/src/Processors/AugmentTags.php
index d888f94e..a19633e4 100644
--- a/src/Processors/AugmentTags.php
+++ b/src/Processors/AugmentTags.php
@@ -16,7 +16,7 @@
 class AugmentTags implements ProcessorInterface
 {
 
-    /** @var array<string>  */
+    /** @var array<string> */
     protected $unusedTagsToKeepWhitelist = [];
 
     public function __construct(array $unusedTagsToKeepWhitelist = [])
diff --git a/tests/Processors/AugmentTagsTest.php b/tests/Processors/AugmentTagsTest.php
index 2a8c178c..b68ce587 100644
--- a/tests/Processors/AugmentTagsTest.php
+++ b/tests/Processors/AugmentTagsTest.php
@@ -50,7 +50,7 @@ public function testAllowUnusedTags(): void
             static::processors(),
             null,
             [
-                'augmentTags' => ['unusedTagsToKeepWhitelist' => ['fancy']]
+                'augmentTags' => ['unusedTagsToKeepWhitelist' => ['fancy']],
             ]
         );
 

From 8035bcb30ed7f78f0455e7b45d246b0d5d1287f7 Mon Sep 17 00:00:00 2001
From: Paul Johnston <paul-johnston@zencontrol.com>
Date: Wed, 28 Aug 2024 14:26:38 +1000
Subject: [PATCH 5/5] Add wildcard argument to AugmentTags whitelist

---
 src/Processors/AugmentTags.php       | 25 ++++++++++++++++++-------
 tests/Processors/AugmentTagsTest.php | 21 ++++++++++++++++++++-
 2 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/src/Processors/AugmentTags.php b/src/Processors/AugmentTags.php
index a19633e4..25290081 100644
--- a/src/Processors/AugmentTags.php
+++ b/src/Processors/AugmentTags.php
@@ -17,16 +17,19 @@ class AugmentTags implements ProcessorInterface
 {
 
     /** @var array<string> */
-    protected $unusedTagsToKeepWhitelist = [];
+    protected $whitelist;
 
-    public function __construct(array $unusedTagsToKeepWhitelist = [])
+    public function __construct(array $whitelist = [])
     {
-        $this->unusedTagsToKeepWhitelist = $unusedTagsToKeepWhitelist;
+        $this->whitelist = $whitelist;
     }
 
-    public function setUnusedTagsToKeepWhitelist(array $unusedTagsToKeepWhitelist): AugmentTags
+    /**
+     * Whitelist tags to keep even if not used. <code>*</code> may be used to keep all unused.
+     */
+    public function setWhitelist(array $whitelist): AugmentTags
     {
-        $this->unusedTagsToKeepWhitelist = $unusedTagsToKeepWhitelist;
+        $this->whitelist = $whitelist;
 
         return $this;
     }
@@ -65,8 +68,16 @@ public function __invoke(Analysis $analysis)
             }
         }
 
-        // remove tags that we don't want to keep (defaults to all unused tags)
-        $tagsToKeep = array_merge($usedTagNames, $this->unusedTagsToKeepWhitelist);
+        $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, $tagsToKeep)) {
                 if (false !== $index = array_search($tag, $analysis->openapi->tags, true)) {
diff --git a/tests/Processors/AugmentTagsTest.php b/tests/Processors/AugmentTagsTest.php
index b68ce587..2d049efe 100644
--- a/tests/Processors/AugmentTagsTest.php
+++ b/tests/Processors/AugmentTagsTest.php
@@ -50,10 +50,29 @@ public function testAllowUnusedTags(): void
             static::processors(),
             null,
             [
-                'augmentTags' => ['unusedTagsToKeepWhitelist' => ['fancy']],
+                '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');
+    }
 }