Allow to disable default tag descriptions (#1859)

Author: DerManoMann

src/Processors/AugmentTags.php

@@ -16,11 +16,13 @@
 class AugmentTags
 {
     /** @var array<string> */
-    protected array $whitelist = [];
+    protected array $whitelist;
+    protected bool $withDescription;
 
-    public function __construct(array $whitelist = [])
+    public function __construct(array $whitelist = [], bool $withDescription = true)
     {
         $this->whitelist = $whitelist;
+        $this->withDescription = $withDescription;
     }
 
     /**
@@ -33,6 +35,16 @@ public function setWhitelist(array $whitelist): AugmentTags
         return $this;
     }
 
+    /**
+     * Enables/disables generation of default tag descriptions.
+     */
+    public function setWithDescription(bool $withDescription): AugmentTags
+    {
+        $this->withDescription = $withDescription;
+
+        return $this;
+    }
+
     public function __invoke(Analysis $analysis): void
     {
         /** @var OA\Operation[] $operations */
@@ -62,7 +74,12 @@ public function __invoke(Analysis $analysis): void
             $declatedTagNames = array_keys($declaredTags);
             foreach ($usedTagNames as $tagName) {
                 if (!in_array($tagName, $declatedTagNames)) {
-                    $analysis->openapi->merge([new OA\Tag(['name' => $tagName, 'description' => $tagName])]);
+                    $analysis->openapi->merge([new OA\Tag([
+                        'name' => $tagName,
+                        'description' => $this->withDescription
+                            ? $tagName
+                            : Generator::UNDEFINED,
+                    ])]);
                 }
             }
         }

tests/Processors/AugmentTagsTest.php

@@ -6,6 +6,7 @@
 
 namespace OpenApi\Tests\Processors;
 
+use OpenApi\Generator;
 use OpenApi\Tests\OpenApiTestCase;
 
 class AugmentTagsTest extends OpenApiTestCase
@@ -67,4 +68,23 @@ public function testAllowUnusedTagsWildcard(): void
 
         $this->assertCount(3, $analysis->openapi->tags, 'Expecting all tags to be preserved');
     }
+
+    /**
+     * @requires PHP 8.1
+     */
+    public function testWithoutDescriptions(): void
+    {
+        $analysis = $this->analysisFromFixtures(
+            ['Processors/EntityControllerClass.php'],
+            static::processors(),
+            null,
+            [
+                'augmentTags' => ['withDescription' => false],
+            ]
+        );
+
+        $this->assertNotEmpty($analysis->openapi->tags);
+        $firstTag = $analysis->openapi->tags[0];
+        $this->assertEquals(Generator::UNDEFINED, $firstTag->description);
+    }
 }