Add AugmentTags processor (#1615)

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

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

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

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

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(),
             ]);
         }

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])]);
+                }
+            }
+        }
+    }
+}

tests/Fixtures/Scratch/ComplexCustomAttributes3.0.0.yaml

@@ -61,3 +61,7 @@ components:
       title: TargetId
     TargetType:
       title: TargetType
+tags:
+  -
+    name: 'Target groups'
+    description: 'Target groups'

tests/Fixtures/Scratch/ComplexCustomAttributes3.1.0.yaml

@@ -61,3 +61,7 @@ components:
       title: TargetId
     TargetType:
       title: TargetType
+tags:
+  -
+    name: 'Target groups'
+    description: 'Target groups'

tests/Fixtures/Scratch/ParameterContent3.0.0.yaml

@@ -24,3 +24,7 @@ paths:
       responses:
         '200':
           description: OK
+tags:
+  -
+    name: endpoints
+    description: endpoints

tests/Fixtures/Scratch/ParameterContent3.1.0.yaml

@@ -24,3 +24,7 @@ paths:
       responses:
         '200':
           description: OK
+tags:
+  -
+    name: endpoints
+    description: endpoints

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: '[email protected]')
+)
+]
+#[OAT\Get(
+    path: '/endpoint',
+    description: 'Sandbox endpoint',
+    tags: ['sandbox'],
+    responses: [
+        new OAT\Response(
+            response: 200,
+            description: 'All good'
+        ),
+    ]
+)]
+class TagsEndpoint
+{
+}

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: [email protected]
+  version: '1.0'
+paths:
+  /endpoint:
+    get:
+      tags:
+        - sandbox
+      description: 'Sandbox endpoint'
+      operationId: f1c7f5a59b9708596c2bc955017002e6
+      responses:
+        '200':
+          description: 'All good'
+tags:
+  -
+    name: sandbox
+    description: sandbox

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: [email protected]
+  version: '1.0'
+paths:
+  /endpoint:
+    get:
+      tags:
+        - sandbox
+      description: 'Sandbox endpoint'
+      operationId: f1c7f5a59b9708596c2bc955017002e6
+      responses:
+        '200':
+          description: 'All good'
+tags:
+  -
+    name: sandbox
+    description: sandbox