From 5eb7a903216e1086e9467c5f2979c2db9c5c3309 Mon Sep 17 00:00:00 2001
From: Martin Rademacher <mano@radebatz.net>
Date: Tue, 2 Jul 2024 14:40:43 +1200
Subject: [PATCH] Add `AugmentTags` processor (#1615)

---
 Examples/swagger-spec/petstore/petstore.yaml  | 10 +++++
 .../using-links-php81/using-links-php81.yaml  |  4 ++
 Examples/using-refs/using-refs.yaml           | 10 +++++
 Examples/using-traits/using-traits.yaml       |  7 +++
 src/Generator.php                             |  1 +
 src/Processors/AugmentTags.php                | 44 +++++++++++++++++++
 .../Scratch/ComplexCustomAttributes3.0.0.yaml |  4 ++
 .../Scratch/ComplexCustomAttributes3.1.0.yaml |  4 ++
 .../Scratch/ParameterContent3.0.0.yaml        |  4 ++
 .../Scratch/ParameterContent3.1.0.yaml        |  4 ++
 tests/Fixtures/Scratch/Tags.php               | 31 +++++++++++++
 tests/Fixtures/Scratch/Tags3.0.0.yaml         | 22 ++++++++++
 tests/Fixtures/Scratch/Tags3.1.0.yaml         | 22 ++++++++++
 13 files changed, 167 insertions(+)
 create mode 100644 src/Processors/AugmentTags.php
 create mode 100644 tests/Fixtures/Scratch/Tags.php
 create mode 100644 tests/Fixtures/Scratch/Tags3.0.0.yaml
 create mode 100644 tests/Fixtures/Scratch/Tags3.1.0.yaml

diff --git a/Examples/swagger-spec/petstore/petstore.yaml b/Examples/swagger-spec/petstore/petstore.yaml
index 845dd2dd6..efefad4ba 100644
--- a/Examples/swagger-spec/petstore/petstore.yaml
+++ b/Examples/swagger-spec/petstore/petstore.yaml
@@ -93,3 +93,13 @@ components:
         tag:
           type: string
       type: object
+tags:
+  -
+    name: pets
+    description: pets
+  -
+    name: pets
+    description: pets
+  -
+    name: pets
+    description: pets
diff --git a/Examples/using-links-php81/using-links-php81.yaml b/Examples/using-links-php81/using-links-php81.yaml
index 9279d8165..d2a2d02e8 100644
--- a/Examples/using-links-php81/using-links-php81.yaml
+++ b/Examples/using-links-php81/using-links-php81.yaml
@@ -240,3 +240,7 @@ components:
         username: '$response.body#/author/username'
         slug: '$response.body#/repository/slug'
         pid: '$response.body#/id'
+tags:
+  -
+    name: Users
+    description: Users
diff --git a/Examples/using-refs/using-refs.yaml b/Examples/using-refs/using-refs.yaml
index 5481817ac..cf0830e20 100644
--- a/Examples/using-refs/using-refs.yaml
+++ b/Examples/using-refs/using-refs.yaml
@@ -96,3 +96,13 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/Product'
+tags:
+  -
+    name: Products
+    description: Products
+  -
+    name: Products
+    description: Products
+  -
+    name: Products
+    description: Products
diff --git a/Examples/using-traits/using-traits.yaml b/Examples/using-traits/using-traits.yaml
index 8227ac1a5..3666e2dd2 100644
--- a/Examples/using-traits/using-traits.yaml
+++ b/Examples/using-traits/using-traits.yaml
@@ -133,3 +133,10 @@ components:
               description: 'The trick.'
               example: 'recite poem'
           type: object
+tags:
+  -
+    name: Entities
+    description: Entities
+  -
+    name: Products
+    description: Products
diff --git a/src/Generator.php b/src/Generator.php
index f499e95fc..ebcbf3200 100644
--- a/src/Generator.php
+++ b/src/Generator.php
@@ -275,6 +275,7 @@ public function getProcessorPipeline(): Pipeline
                 new Processors\MergeJsonContent(),
                 new Processors\MergeXmlContent(),
                 new Processors\OperationId(),
+                new Processors\AugmentTags(),
                 new Processors\CleanUnmerged(),
             ]);
         }
diff --git a/src/Processors/AugmentTags.php b/src/Processors/AugmentTags.php
new file mode 100644
index 000000000..0aeb8fce9
--- /dev/null
+++ b/src/Processors/AugmentTags.php
@@ -0,0 +1,44 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Processors;
+
+use OpenApi\Analysis;
+use OpenApi\Annotations as OA;
+use OpenApi\Generator;
+
+/**
+ * Ensures that all tags used on operations also exist in the global <code>tags</code> list.
+ */
+class AugmentTags implements ProcessorInterface
+{
+    public function __invoke(Analysis $analysis)
+    {
+        /** @var OA\Operation[] $operations */
+        $operations = $analysis->getAnnotationsOfType(OA\Operation::class);
+
+        $usedTags = [];
+        foreach ($operations as $operation) {
+            if (!Generator::isDefault($operation->tags)) {
+                $usedTags = array_merge($usedTags, $operation->tags);
+            }
+        }
+
+        if ($usedTags) {
+            $declaredTags = [];
+            if (!Generator::isDefault($analysis->openapi->tags)) {
+                foreach ($analysis->openapi->tags as $tag) {
+                    $declaredTags[] = $tag->name;
+                }
+            }
+            foreach ($usedTags as $tag) {
+                if (!in_array($tag, $declaredTags)) {
+                    $analysis->openapi->merge([new OA\Tag(['name' => $tag, 'description' => $tag])]);
+                }
+            }
+        }
+    }
+}
diff --git a/tests/Fixtures/Scratch/ComplexCustomAttributes3.0.0.yaml b/tests/Fixtures/Scratch/ComplexCustomAttributes3.0.0.yaml
index a2e25b93c..08e2245d5 100644
--- a/tests/Fixtures/Scratch/ComplexCustomAttributes3.0.0.yaml
+++ b/tests/Fixtures/Scratch/ComplexCustomAttributes3.0.0.yaml
@@ -61,3 +61,7 @@ components:
       title: TargetId
     TargetType:
       title: TargetType
+tags:
+  -
+    name: 'Target groups'
+    description: 'Target groups'
diff --git a/tests/Fixtures/Scratch/ComplexCustomAttributes3.1.0.yaml b/tests/Fixtures/Scratch/ComplexCustomAttributes3.1.0.yaml
index d2d9b15bf..56feb209a 100644
--- a/tests/Fixtures/Scratch/ComplexCustomAttributes3.1.0.yaml
+++ b/tests/Fixtures/Scratch/ComplexCustomAttributes3.1.0.yaml
@@ -61,3 +61,7 @@ components:
       title: TargetId
     TargetType:
       title: TargetType
+tags:
+  -
+    name: 'Target groups'
+    description: 'Target groups'
diff --git a/tests/Fixtures/Scratch/ParameterContent3.0.0.yaml b/tests/Fixtures/Scratch/ParameterContent3.0.0.yaml
index 6011a95b1..1a338627e 100644
--- a/tests/Fixtures/Scratch/ParameterContent3.0.0.yaml
+++ b/tests/Fixtures/Scratch/ParameterContent3.0.0.yaml
@@ -24,3 +24,7 @@ paths:
       responses:
         '200':
           description: OK
+tags:
+  -
+    name: endpoints
+    description: endpoints
diff --git a/tests/Fixtures/Scratch/ParameterContent3.1.0.yaml b/tests/Fixtures/Scratch/ParameterContent3.1.0.yaml
index 71fadccf0..0df4db40c 100644
--- a/tests/Fixtures/Scratch/ParameterContent3.1.0.yaml
+++ b/tests/Fixtures/Scratch/ParameterContent3.1.0.yaml
@@ -24,3 +24,7 @@ paths:
       responses:
         '200':
           description: OK
+tags:
+  -
+    name: endpoints
+    description: endpoints
diff --git a/tests/Fixtures/Scratch/Tags.php b/tests/Fixtures/Scratch/Tags.php
new file mode 100644
index 000000000..09f15c059
--- /dev/null
+++ b/tests/Fixtures/Scratch/Tags.php
@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Tests\Fixtures\Scratch;
+
+use OpenApi\Attributes as OAT;
+
+#[OAT\Info(
+    title: 'Tags',
+    description: 'Tag Scratch',
+    version: '1.0',
+    contact: new OAT\Contact(name: 'contact', email: 'contact@example.com')
+)
+]
+#[OAT\Get(
+    path: '/endpoint',
+    description: 'Sandbox endpoint',
+    tags: ['sandbox'],
+    responses: [
+        new OAT\Response(
+            response: 200,
+            description: 'All good'
+        ),
+    ]
+)]
+class TagsEndpoint
+{
+}
diff --git a/tests/Fixtures/Scratch/Tags3.0.0.yaml b/tests/Fixtures/Scratch/Tags3.0.0.yaml
new file mode 100644
index 000000000..0d6caf6fc
--- /dev/null
+++ b/tests/Fixtures/Scratch/Tags3.0.0.yaml
@@ -0,0 +1,22 @@
+openapi: 3.0.0
+info:
+  title: Tags
+  description: 'Tag Scratch'
+  contact:
+    name: contact
+    email: contact@example.com
+  version: '1.0'
+paths:
+  /endpoint:
+    get:
+      tags:
+        - sandbox
+      description: 'Sandbox endpoint'
+      operationId: f1c7f5a59b9708596c2bc955017002e6
+      responses:
+        '200':
+          description: 'All good'
+tags:
+  -
+    name: sandbox
+    description: sandbox
diff --git a/tests/Fixtures/Scratch/Tags3.1.0.yaml b/tests/Fixtures/Scratch/Tags3.1.0.yaml
new file mode 100644
index 000000000..013508b9b
--- /dev/null
+++ b/tests/Fixtures/Scratch/Tags3.1.0.yaml
@@ -0,0 +1,22 @@
+openapi: 3.1.0
+info:
+  title: Tags
+  description: 'Tag Scratch'
+  contact:
+    name: contact
+    email: contact@example.com
+  version: '1.0'
+paths:
+  /endpoint:
+    get:
+      tags:
+        - sandbox
+      description: 'Sandbox endpoint'
+      operationId: f1c7f5a59b9708596c2bc955017002e6
+      responses:
+        '200':
+          description: 'All good'
+tags:
+  -
+    name: sandbox
+    description: sandbox