Merge pull request #47 from cnizzardini/enhancement/42-custom-operati…

…on-tags

Override default tag attribute #42

README.md

@@ -234,11 +234,12 @@ public function index() {}
 ```
 
 #### `@Swag\SwagOperation`
-Method level annotation for hiding a controller action from swagger.
+Method level annotation for OpenApi Operations. Toggle visibility with isVisible and customize tag names which default 
+to the controllers name.
 
 ```php
 /**
- * @SwagOperation(isVisible=false)
+ * @SwagOperation(isVisible=false, tagNames={"MyTag","AnotherTag"})
  */
 public function index() {}
 ```

src/Lib/Annotation/SwagOperation.php

@@ -9,16 +9,21 @@
  * @Target({"METHOD"})
  * @Attributes({
  *   @Attribute("isVisible", type="bool"),
+ *   @Attribute("tagNames", type="array"),
  * })
  */
 class SwagOperation
 {
     /** @var bool */
     public $isVisible;
 
+    /** @var string[] */
+    public $tagNames;
+
     public function __construct(array $values)
     {
-        $values = array_merge(['isVisible' => true], $values);
+        $values = array_merge(['isVisible' => true, 'tagNames' => []], $values);
         $this->isVisible = (bool) $values['isVisible'];
+        $this->tagNames = $values['tagNames'];
     }
 }

src/Lib/Operation/OperationFromRouteFactory.php

@@ -62,10 +62,9 @@ public function create(RouteDecorator $route, string $httpMethod, ?Schema $schem
             ->setSummary($docBlock->getSummary())
             ->setDescription($docBlock->getDescription())
             ->setHttpMethod(strtolower($httpMethod))
-            ->setOperationId($route->getName())
-            ->setTags([
-                Inflector::humanize(Inflector::underscore($route->getController()))
-            ]);
+            ->setOperationId($route->getName());
+
+        $operation = $this->getOperationWithTags($operation, $route, $annotations);
 
         $args = [$config, $operation, $docBlock, $annotations, $route, $schema];
 
@@ -142,4 +141,27 @@ private function isVisible(array $annotations) : bool
 
         return $swagOperation->isVisible === false ? false : true;
     }
+
+    /**
+     * @param Operation $operation
+     * @param RouteDecorator $route
+     * @param array $annotations
+     * @return Operation]
+     */
+    private function getOperationWithTags(Operation $operation, RouteDecorator $route, array $annotations) : Operation
+    {
+        $swagOperations = array_filter($annotations, function ($annotation) {
+            return $annotation instanceof SwagOperation;
+        });
+
+        $swagOperation = reset($swagOperations);
+
+        if (empty($swagOperation->tagNames)) {
+            return $operation->setTags([
+                Inflector::humanize(Inflector::underscore($route->getController()))
+            ]);
+        }
+
+        return $operation->setTags($swagOperation->tagNames);
+    }
 }

tests/TestCase/Lib/Operation/OperationFromRouteFactoryTest.php

@@ -59,8 +59,10 @@ public function testCreate()
         $route = reset($routes);
 
         $operation = (new OperationFromRouteFactory($swagger))->create($route, 'GET', null);
+
         $this->assertInstanceOf(Operation::class, $operation);
         $this->assertEquals('GET', $operation->getHttpMethod());
         $this->assertEquals('employees:index', $operation->getOperationId());
+        $this->assertEquals('CustomTag', $operation->getTags()[1]);
     }
 }

tests/test_app/src/Controller/EmployeesController.php

@@ -27,6 +27,7 @@ public function initialize() : void
     /**
      * Gets Employees
      *
+     * @Swag\SwagOperation(tagNames={"Employees","CustomTag"})
      * @return \Cake\Http\Response|null|void Renders view
      */
     public function index()