Implemented Data Structures

Moved data structures to the end so resource groups don't get split up

Consolidate all data structures into one section

Restructured

Applied style ci patch

Author: Tobias Kündig

src/Annotation/Attribute.php

@@ -13,7 +13,7 @@ class Attribute
     public $identifier;
 
     /**
-     * @var string
+     * @var mixed
      */
     public $type = 'string';
 

src/Annotation/DataStructures.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Dingo\Blueprint\Annotation;
+
+/**
+ * @Annotation
+ */
+class DataStructures
+{
+    /**
+     * @array<Type>
+     */
+    public $value;
+}

src/Annotation/Property.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Dingo\Blueprint\Annotation;
+
+/**
+ * @Annotation
+ */
+class Property
+{
+    /**
+     * @var string
+     */
+    public $identifier;
+
+    /**
+     * @var string
+     */
+    public $type = 'string';
+
+    /**
+     * @var string
+     */
+    public $description;
+
+    /**
+     * @var mixed
+     */
+    public $sample;
+}

src/Annotation/Request.php

@@ -31,4 +31,9 @@ class Request
      * @var array<Dingo\Blueprint\Annotation\Attribute>
      */
     public $attributes;
+
+    /**
+     * @var Dingo\Blueprint\Annotation\Type
+     */
+    public $type;
 }

src/Annotation/Response.php

@@ -31,4 +31,9 @@ class Response
      * @var array<Dingo\Blueprint\Annotation\Attribute>
      */
     public $attributes;
+
+    /**
+     * @var Dingo\Blueprint\Annotation\Type
+     */
+    public $type;
 }

src/Annotation/Type.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Dingo\Blueprint\Annotation;
+
+/**
+ * @Annotation
+ */
+class Type
+{
+    /**
+     * @var string
+     */
+    public $identifier;
+
+    /**
+     * @var mixed
+     */
+    public $type;
+
+    /**
+     * @array<Property>
+     */
+    public $properties;
+}

src/Blueprint.php

@@ -2,6 +2,7 @@
 
 namespace Dingo\Blueprint;
 
+use Dingo\Blueprint\Annotation\Type;
 use ReflectionClass;
 use RuntimeException;
 use Illuminate\Support\Str;
@@ -135,7 +136,9 @@ protected function generateContentsFromResources(Collection $resources, $name)
         $contents .= sprintf('# %s', $name);
         $contents .= $this->line(2);
 
-        $resources->each(function ($resource) use (&$contents) {
+        $globalDataStructures = new Collection();
+
+        $resources->each(function ($resource) use (&$contents, $globalDataStructures) {
             if ($resource->getActions()->isEmpty()) {
                 return;
             }
@@ -160,6 +163,10 @@ protected function generateContentsFromResources(Collection $resources, $name)
                     $contents .= $description;
                 }
 
+                if (($dataStructures = $resource->getDataStructures()) && ! $dataStructures->isEmpty()) {
+                    $globalDataStructures->push($dataStructures);
+                }
+
                 if (($attributes = $action->getAttributes()) && ! $attributes->isEmpty()) {
                     $this->appendAttributes($contents, $attributes);
                 }
@@ -192,6 +199,15 @@ protected function generateContentsFromResources(Collection $resources, $name)
             $contents .= $this->line(2);
         });
 
+        if (! $globalDataStructures->isEmpty()) {
+            $contents .= $this->line(1);
+            $contents .= '# Data Structures';
+
+            $globalDataStructures->each(function ($dataStructure) use (&$contents) {
+                $this->appendDataStructures($contents, $dataStructure);
+            });
+        }
+
         return stripslashes(trim($contents));
     }
 
@@ -217,15 +233,35 @@ protected function appendAttributes(&$contents, Collection $attributes, $indent
                 $contents .= sprintf(': %s', $attribute->sample);
             }
 
+            $arrayType = false;
+            if (is_array($attribute->type)) {
+                $arrayType = true;
+                $attribute->type = array_shift($attribute->type);
+            }
+
+            $type = $this->resolveType($attribute->type);
+
             $contents .= sprintf(
                 ' (%s, %s) - %s',
-                $attribute->type,
+                $arrayType ? "array[${type}]" : $type,
                 $attribute->required ? 'required' : 'optional',
                 $attribute->description
             );
         });
     }
 
+    /**
+     * Append a type attribute to a resource or action.
+     *
+     * @param string $contents
+     * @param Type   $type
+     * @param int    $indent
+     */
+    protected function appendType(&$contents, Type $type, $indent = 0)
+    {
+        $this->appendSection($contents, sprintf('Attributes (%s)', $type->identifier), $indent);
+    }
+
     /**
      * Append the parameters subsection to a resource or action.
      *
@@ -284,7 +320,9 @@ protected function appendResponse(&$contents, Annotation\Response $response, Res
             $this->appendHeaders($contents, array_merge($resource->getResponseHeaders(), $response->headers));
         }
 
-        if (isset($response->attributes)) {
+        if (isset($response->type)) {
+            $this->appendType($contents, $response->type, 1);
+        } elseif (isset($response->attributes)) {
             $this->appendAttributes($contents, collect($response->attributes), 1);
         }
 
@@ -316,7 +354,9 @@ protected function appendRequest(&$contents, $request, Resource $resource)
             $this->appendHeaders($contents, array_merge($resource->getRequestHeaders(), $request->headers));
         }
 
-        if (isset($request->attributes)) {
+        if (isset($request->type)) {
+            $this->appendType($contents, $request->type, 1);
+        } elseif (isset($request->attributes)) {
             $this->appendAttributes($contents, collect($request->attributes), 1);
         }
 
@@ -388,6 +428,66 @@ protected function appendSection(&$contents, $name, $indent = 0, $lines = 2)
         $contents .= '+ '.$name;
     }
 
+    /**
+     * Append data structures.
+     *
+     * @param $contents
+     * @param $allStructures
+     */
+    protected function appendDataStructures(&$contents, $allStructures)
+    {
+        $allStructures->each(function ($dataStructures) use (&$contents) {
+            collect($dataStructures->value)->each(function ($type) use (&$contents) {
+
+                $contents .= $this->line(2);
+                $contents .= sprintf('## %s (%s)', $type->identifier, $this->resolveType($type->type));
+                $contents .= $this->line(1);
+
+                if (isset($type->properties)) {
+                    $this->appendProperties($contents, collect($type->properties), -1, false);
+                }
+            });
+        });
+    }
+
+    /**
+     * Resolves the name of a type from either a string or a Type class.
+     *
+     * @param string|Type $type
+     *
+     * @return string
+     */
+    protected function resolveType($type)
+    {
+        return $type instanceof Type ? $type->identifier : $type;
+    }
+
+    /**
+     * Append the properties to a type.
+     *
+     * @param string                         $contents
+     * @param \Illuminate\Support\Collection $properties
+     *
+     * @return void
+     */
+    protected function appendProperties(&$contents, Collection $properties)
+    {
+        $properties->each(function ($property) use (&$contents) {
+            $contents .= $this->line();
+            $contents .= sprintf('+ %s', $property->identifier);
+
+            if ($property->sample) {
+                $contents .= sprintf(': %s', $property->sample);
+            }
+
+            $contents .= sprintf(
+                ' (%s) - %s',
+                $property->type,
+                $property->description
+            );
+        });
+    }
+
     /**
      * Prepare a body.
      *

src/Resource.php

@@ -2,6 +2,7 @@
 
 namespace Dingo\Blueprint;
 
+use Dingo\Blueprint\Annotation\DataStructures;
 use Illuminate\Support\Collection;
 use ReflectionClass;
 use phpDocumentor\Reflection\DocBlock;
@@ -108,6 +109,18 @@ public function getActions()
         return $this->actions;
     }
 
+    /**
+     * Get the data structures belonging to the resource.
+     *
+     * @return \Illuminate\Support\Collection
+     */
+    public function getDataStructures()
+    {
+        return $this->annotations->filter(function ($annotation) {
+            return $annotation instanceof DataStructures;
+        });
+    }
+
     /**
      * get the resource URI.
      *

tests/BlueprintTest.php

@@ -487,4 +487,60 @@ public function testGeneratingSimpleBlueprints()
 
         $this->assertEquals(trim($expected), $blueprint->generate($resources, 'testing', 'v1', null));
     }
+
+    public function testGeneratingBlueprintsWithDataStructures()
+    {
+        $resources = new Collection([new Stubs\AccountController]);
+
+        $blueprint = new Blueprint(new SimpleAnnotationReader, new Filesystem);
+
+        $expected = <<<'EOT'
+FORMAT: 1A
+
+# testing
+
+# Account [/accounts]
+
+## Show all accounts. [GET /accounts]
+
+
++ Response 200 (application/json)
+
+    + Attributes
+        + success: true (boolean, required) - Status of the request
+        + data (array[Account], required) - The account's data
+
+## Show a specific account. [GET /accounts/1]
+
+
++ Response 200 (application/json)
+
+    + Attributes
+        + success: true (boolean, required) - Status of the request
+        + data (Deposit, required) - The account's data
+
+## Create a new account. [POST /accounts]
+
+
++ Request (application/json)
+
+    + Attributes (Account)
+
++ Response 200 (application/json)
+
+    + Attributes (Account)
+
+
+# Data Structures
+
+## Account (object)
+
++ name: Savings (string) - The account name
++ balance: 1200 (number) - The account balance
+
+## Deposit (Account)
+
+EOT;
+        $this->assertEquals(trim($expected), $blueprint->generate($resources, 'testing', 'v1', null));
+    }
 }