Add group notation - #33 improvement

.travis.yml

@@ -1,5 +1,7 @@
 language: php
 
+dist: trusty
+
 php:
   - 5.5.9
   - 5.5

readme.md

@@ -18,6 +18,8 @@ Some index method phpdoc example:
 /**
  * Products
  *
+ * @Group("Products")
+ * @Versions({"v1"})
  * @Resource("Products", uri="/products")
 */
 class ProductsController extends ApiController

src/Action.php

@@ -60,7 +60,9 @@ public function getDefinition()
             $definition = $identifier.' ['.$definition.']';
         }
 
-        return '## '.$definition;
+        $level = $this->resource->getGroupIdentifier() ? '### ' : '## ';
+
+        return $level.$definition;
     }
 
     /**

src/Annotation/Group.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Dingo\Blueprint\Annotation;
+
+/**
+ * @Annotation
+ */
+class Group
+{
+    /**
+     * @var string
+     */
+    public $identifier;
+}

src/Blueprint.php

@@ -84,7 +84,9 @@ public function generate(Collection $controllers, $name, $version, $includePath
     {
         $this->includePath = $includePath;
 
-        $resources = $controllers->map(function ($controller) use ($version) {
+        $groups = new Collection;
+
+        $resources = $controllers->map(function ($controller) use ($version, $groups) {
             $controller = $controller instanceof ReflectionClass ? $controller : new ReflectionClass($controller);
 
             $actions = new Collection;
@@ -108,25 +110,48 @@ public function generate(Collection $controllers, $name, $version, $includePath
 
             $annotations = new Collection($this->reader->getClassAnnotations($controller));
 
-            return new Resource($controller->getName(), $controller, $annotations, $actions);
+            $versions = $annotations->filter(function($item) {
+                return $item instanceof Annotation\Versions;
+            })->first();
+
+            // if the group does not have the intended version, the group is skipped
+            if( isset($versions->value) && in_array($version, $versions->value) )
+            {
+                $resource = new Resource($controller->getName(), $controller, $annotations, $actions);
+
+                // Find or create group and add resource to it
+                $group = $groups->where('identifier', $resource->getGroupIdentifier())->first() ?: new Group($resource);
+                $group->addResource($resource);
+                if (! $resource->getGroupIdentifier()) {
+                    // Prepend resource group with no identifier so this group appears first
+                    $groups->contains($group) ?: $groups->prepend($group);
+                } else {
+                    $groups->contains($group) ?: $groups->push($group);
+                }
+
+                return $resource;
+            }
+
+
+            return false;
         });
 
-        $contents = $this->generateContentsFromResources($resources, $name);
+        $contents = $this->generateContentsFromGroups($groups, $name);
 
         $this->includePath = null;
 
         return $contents;
     }
 
     /**
-     * Generate the documentation contents from the resources collection.
+     * Generate the documentation contents from the groups collection.
      *
-     * @param \Illuminate\Support\Collection $resources
+     * @param \Illuminate\Support\Collection $groups
      * @param string                         $name
      *
      * @return string
      */
-    protected function generateContentsFromResources(Collection $resources, $name)
+    protected function generateContentsFromGroups(Collection $groups, $name)
     {
         $contents = '';
 
@@ -135,61 +160,70 @@ protected function generateContentsFromResources(Collection $resources, $name)
         $contents .= sprintf('# %s', $name);
         $contents .= $this->line(2);
 
-        $resources->each(function ($resource) use (&$contents) {
-            if ($resource->getActions()->isEmpty()) {
-                return;
-            }
-
-            $contents .= $resource->getDefinition();
+        $groups->each(function ($group) use (&$contents) {
 
-            if ($description = $resource->getDescription()) {
-                $contents .= $this->line();
-                $contents .= $description;
+            if ($group->getIdentifier()) {
+                $contents .= $group->getDefinition();
+                $contents .= $this->line(2);
             }
 
-            if (($parameters = $resource->getParameters()) && ! $parameters->isEmpty()) {
-                $this->appendParameters($contents, $parameters);
-            }
+            $group->getResources()->each(function ($resource) use (&$contents) {
 
-            $resource->getActions()->each(function ($action) use (&$contents, $resource) {
-                $contents .= $this->line(2);
-                $contents .= $action->getDefinition();
+                if ($resource->getActions()->isEmpty()) {
+                    return;
+                }
+
+                $contents .= $resource->getDefinition();
 
-                if ($description = $action->getDescription()) {
+                if ($description = $resource->getDescription()) {
                     $contents .= $this->line();
                     $contents .= $description;
                 }
 
-                if (($attributes = $action->getAttributes()) && ! $attributes->isEmpty()) {
-                    $this->appendAttributes($contents, $attributes);
-                }
-
-                if (($parameters = $action->getParameters()) && ! $parameters->isEmpty()) {
+                if (($parameters = $resource->getParameters()) && ! $parameters->isEmpty()) {
                     $this->appendParameters($contents, $parameters);
                 }
 
-                if ($request = $action->getRequest()) {
-                    $this->appendRequest($contents, $request, $resource);
-                }
+                $resource->getActions()->each(function ($action) use (&$contents, $resource) {
+                    $contents .= $this->line(2);
+                    $contents .= $action->getDefinition();
 
-                if ($response = $action->getResponse()) {
-                    $this->appendResponse($contents, $response, $resource);
-                }
+                    if ($description = $action->getDescription()) {
+                        $contents .= $this->line();
+                        $contents .= $description;
+                    }
+
+                    if (($attributes = $action->getAttributes()) && ! $attributes->isEmpty()) {
+                        $this->appendAttributes($contents, $attributes);
+                    }
+
+                    if (($parameters = $action->getParameters()) && ! $parameters->isEmpty()) {
+                        $this->appendParameters($contents, $parameters);
+                    }
 
-                if ($transaction = $action->getTransaction()) {
-                    foreach ($transaction->value as $value) {
-                        if ($value instanceof Annotation\Request) {
-                            $this->appendRequest($contents, $value, $resource);
-                        } elseif ($value instanceof Annotation\Response) {
-                            $this->appendResponse($contents, $value, $resource);
-                        } else {
-                            throw new RuntimeException('Unsupported annotation type given in transaction.');
+                    if ($request = $action->getRequest()) {
+                        $this->appendRequest($contents, $request, $resource);
+                    }
+
+                    if ($response = $action->getResponse()) {
+                        $this->appendResponse($contents, $response, $resource);
+                    }
+
+                    if ($transaction = $action->getTransaction()) {
+                        foreach ($transaction->value as $value) {
+                            if ($value instanceof Annotation\Request) {
+                                $this->appendRequest($contents, $value, $resource);
+                            } elseif ($value instanceof Annotation\Response) {
+                                $this->appendResponse($contents, $value, $resource);
+                            } else {
+                                throw new RuntimeException('Unsupported annotation type given in transaction.');
+                            }
                         }
                     }
-                }
-            });
+                });
 
-            $contents .= $this->line(2);
+                $contents .= $this->line(2);
+            });
         });
 
         return stripslashes(trim($contents));
@@ -405,7 +439,7 @@ protected function prepareBody($body, $contentType)
                 $path .= '.json';
             }
 
-            $body = $this->files->get($this->includePath.'/'.$path);
+            $body = $this->files->get($includePath.'/'.$path);
 
             json_decode($body);
 
@@ -454,4 +488,4 @@ protected function getFormat()
     {
         return 'FORMAT: 1A';
     }
-}
+}

src/Group.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace Dingo\Blueprint;
+
+use Illuminate\Support\Collection;
+
+class Group extends Section
+{
+    /**
+     * Group identifier.
+     *
+     * @var string
+     */
+    public $identifier = null;
+
+    /**
+     * Collection of resources belonging to group.
+     *
+     * @var array
+     */
+    protected $resources;
+
+    /**
+     * Create a new group instance.
+     *
+     * @param \Dingo\Blueprint\Resource $resource
+     *
+     * @return void
+     */
+    public function __construct(Resource $resource)
+    {
+        $this->resources = new Collection([$resource]);
+        $this->identifier = $resource->getGroupIdentifier();
+    }
+
+    /**
+     * Get the group identifier.
+     *
+     * @return string|null
+     */
+    public function getIdentifier()
+    {
+        return $this->identifier;
+    }
+
+    /**
+     * Add resource to the group.
+     *
+     * @param \Dingo\Blueprint\Resource $resource
+     *
+     * @return void
+     */
+    public function addResource(Resource $resource)
+    {
+        $this->resources->contains($resource) ?: $this->resources->push($resource);
+    }
+
+    /**
+     * Get the resources belonging to the group.
+     *
+     * @return \Illuminate\Support\Collection
+     */
+    public function getResources()
+    {
+        return $this->resources;
+    }
+
+    /**
+     * Get the group definition.
+     *
+     * @return string
+     */
+    public function getDefinition()
+    {
+        if ($this->identifier) {
+            return '# Group '.$this->identifier;
+        }
+    }
+}

src/Resource.php

@@ -4,6 +4,7 @@
 
 use Illuminate\Support\Collection;
 use ReflectionClass;
+use phpDocumentor\Reflection\DocBlock;
 
 class Resource extends Section
 {
@@ -94,7 +95,31 @@ public function getDefinition()
             $definition = $method.' '.$definition;
         }
 
-        return '# '.$this->getIdentifier().($definition == '/' ? '' : ' ['.$definition.']');
+        $level = $this->getGroupIdentifier() ? '## ' : '# ';
+
+        return $level.$this->getIdentifier().($definition == '/' ? '' : ' ['.$definition.']');
+    }
+
+    /**
+     * Get the resource group annotation.
+     *
+     * @return \Dingo\Blueprint\Annotation\Group
+     */
+    public function getGroupAnnotation()
+    {
+        return $this->getAnnotationByType('Group');
+    }
+
+    /**
+     * Get the resource group.
+     *
+     * @return string
+     */
+    public function getGroupIdentifier()
+    {
+        if (($annotation = $this->getGroupAnnotation()) && isset($annotation->identifier)) {
+            return $annotation->identifier;
+        }
     }
 
     /**
@@ -142,9 +167,7 @@ public function getDescription()
     {
         $factory = \phpDocumentor\Reflection\DocBlockFactory::createInstance();
         $docblock = $factory->create($this->reflector);
-
         $text = $docblock->getSummary().$docblock->getDescription();
-
         return $text;
     }
 
@@ -209,4 +232,4 @@ public function getResponseHeaders()
 
         return $this->responseHeaders;
     }
-}
+}