Merge pull request #84 from vimeo/representation-data-depth-fixes

Representation data depth fixes

resources/examples/Showtimes/Representations/Movie.php

@@ -93,7 +93,14 @@ public function create()
             /**
              * @api-data rotten_tomatoes_score (number) - Rotten Tomatoes score
              */
-            'rotten_tomatoes_score' => $this->rotten_tomatoes_score
+            'rotten_tomatoes_score' => $this->rotten_tomatoes_score,
+
+            'purchase' => [
+                /**
+                 * @api-data purchase.url (string) - URL to purchase the film.
+                 */
+                'url' => $this->purchase->digital->url,
+            ]
         ];
     }
 

resources/examples/Showtimes/blueprints/1.0/api.apib

@@ -3,7 +3,7 @@ FORMAT: 1A
 # Mill unit test API, Showtimes
 This is the API Blueprint file for Mill unit test API, Showtimes.
 
-It was automatically generated by [Mill](https://github.com/vimeo/mill) on 2017-05-09 20:16:14.
+It was automatically generated by [Mill](https://github.com/vimeo/mill) on 2017-05-19 15:23:15.
 
 # Group Movies
 ## Movies [/movie/{id}]
@@ -186,7 +186,7 @@ This action requires a bearer token with `create` scope.
 
 ## Movie
 - `cast` (array[Person]) - Cast
-- `content_rating` (enum[string]) - MPAA rating
+- `content_rating`: `G` (enum[string]) - MPAA rating
     + Members
         + `G`
         + `NC-17`
@@ -202,6 +202,8 @@ This action requires a bearer token with `create` scope.
 - `id` (number) - Unique ID
 - `kid_friendly` (boolean) - Kid friendly?
 - `name` (string) - Name
+- `purchase` (object)
+    - `url` (string) - URL to purchase the film.
 - `rotten_tomatoes_score` (number) - Rotten Tomatoes score
 - `runtime` (string) - Runtime
 - `showtimes` (array) - Non-theater specific showtimes

resources/examples/Showtimes/blueprints/1.0/representations/Movie.apib

@@ -1,6 +1,6 @@
 ## Movie
 - `cast` (array[Person]) - Cast
-- `content_rating` (enum[string]) - MPAA rating
+- `content_rating`: `G` (enum[string]) - MPAA rating
     + Members
         + `G`
         + `NC-17`
@@ -16,6 +16,8 @@
 - `id` (number) - Unique ID
 - `kid_friendly` (boolean) - Kid friendly?
 - `name` (string) - Name
+- `purchase` (object)
+    - `url` (string) - URL to purchase the film.
 - `rotten_tomatoes_score` (number) - Rotten Tomatoes score
 - `runtime` (string) - Runtime
 - `showtimes` (array) - Non-theater specific showtimes

resources/examples/Showtimes/blueprints/1.1.1/api.apib

@@ -3,7 +3,7 @@ FORMAT: 1A
 # Mill unit test API, Showtimes
 This is the API Blueprint file for Mill unit test API, Showtimes.
 
-It was automatically generated by [Mill](https://github.com/vimeo/mill) on 2017-05-09 20:16:14.
+It was automatically generated by [Mill](https://github.com/vimeo/mill) on 2017-05-19 15:23:15.
 
 # Group Movies
 ## Movies [/movie/{id}]
@@ -229,7 +229,7 @@ This action requires a bearer token with `create` scope.
 
 ## Movie
 - `cast` (array[Person]) - Cast
-- `content_rating` (enum[string]) - MPAA rating
+- `content_rating`: `G` (enum[string]) - MPAA rating
     + Members
         + `G`
         + `NC-17`
@@ -249,6 +249,8 @@ This action requires a bearer token with `create` scope.
 - `id` (number) - Unique ID
 - `kid_friendly` (boolean) - Kid friendly?
 - `name` (string) - Name
+- `purchase` (object)
+    - `url` (string) - URL to purchase the film.
 - `rotten_tomatoes_score` (number) - Rotten Tomatoes score
 - `runtime` (string) - Runtime
 - `showtimes` (array) - Non-theater specific showtimes

resources/examples/Showtimes/blueprints/1.1.1/representations/Movie.apib

@@ -1,6 +1,6 @@
 ## Movie
 - `cast` (array[Person]) - Cast
-- `content_rating` (enum[string]) - MPAA rating
+- `content_rating`: `G` (enum[string]) - MPAA rating
     + Members
         + `G`
         + `NC-17`
@@ -20,6 +20,8 @@
 - `id` (number) - Unique ID
 - `kid_friendly` (boolean) - Kid friendly?
 - `name` (string) - Name
+- `purchase` (object)
+    - `url` (string) - URL to purchase the film.
 - `rotten_tomatoes_score` (number) - Rotten Tomatoes score
 - `runtime` (string) - Runtime
 - `showtimes` (array) - Non-theater specific showtimes

resources/examples/Showtimes/blueprints/1.1.2/api.apib

@@ -3,7 +3,7 @@ FORMAT: 1A
 # Mill unit test API, Showtimes
 This is the API Blueprint file for Mill unit test API, Showtimes.
 
-It was automatically generated by [Mill](https://github.com/vimeo/mill) on 2017-05-09 20:16:14.
+It was automatically generated by [Mill](https://github.com/vimeo/mill) on 2017-05-19 15:23:15.
 
 # Group Movies
 ## Movies [/movie/{id}]
@@ -229,7 +229,7 @@ This action requires a bearer token with `create` scope.
 
 ## Movie
 - `cast` (array[Person]) - Cast
-- `content_rating` (enum[string]) - MPAA rating
+- `content_rating`: `G` (enum[string]) - MPAA rating
     + Members
         + `G`
         + `NC-17`
@@ -249,6 +249,8 @@ This action requires a bearer token with `create` scope.
 - `id` (number) - Unique ID
 - `kid_friendly` (boolean) - Kid friendly?
 - `name` (string) - Name
+- `purchase` (object)
+    - `url` (string) - URL to purchase the film.
 - `rotten_tomatoes_score` (number) - Rotten Tomatoes score
 - `runtime` (string) - Runtime
 - `showtimes` (array) - Non-theater specific showtimes

resources/examples/Showtimes/blueprints/1.1.2/representations/Movie.apib

@@ -1,6 +1,6 @@
 ## Movie
 - `cast` (array[Person]) - Cast
-- `content_rating` (enum[string]) - MPAA rating
+- `content_rating`: `G` (enum[string]) - MPAA rating
     + Members
         + `G`
         + `NC-17`
@@ -20,6 +20,8 @@
 - `id` (number) - Unique ID
 - `kid_friendly` (boolean) - Kid friendly?
 - `name` (string) - Name
+- `purchase` (object)
+    - `url` (string) - URL to purchase the film.
 - `rotten_tomatoes_score` (number) - Rotten Tomatoes score
 - `runtime` (string) - Runtime
 - `showtimes` (array) - Non-theater specific showtimes

resources/examples/Showtimes/blueprints/1.1/api.apib

@@ -3,7 +3,7 @@ FORMAT: 1A
 # Mill unit test API, Showtimes
 This is the API Blueprint file for Mill unit test API, Showtimes.
 
-It was automatically generated by [Mill](https://github.com/vimeo/mill) on 2017-05-09 20:16:14.
+It was automatically generated by [Mill](https://github.com/vimeo/mill) on 2017-05-19 15:23:15.
 
 # Group Movies
 ## Movies [/movie/{id}]
@@ -228,7 +228,7 @@ This action requires a bearer token with `create` scope.
 
 ## Movie
 - `cast` (array[Person]) - Cast
-- `content_rating` (enum[string]) - MPAA rating
+- `content_rating`: `G` (enum[string]) - MPAA rating
     + Members
         + `G`
         + `NC-17`
@@ -248,6 +248,8 @@ This action requires a bearer token with `create` scope.
 - `id` (number) - Unique ID
 - `kid_friendly` (boolean) - Kid friendly?
 - `name` (string) - Name
+- `purchase` (object)
+    - `url` (string) - URL to purchase the film.
 - `rotten_tomatoes_score` (number) - Rotten Tomatoes score
 - `runtime` (string) - Runtime
 - `showtimes` (array) - Non-theater specific showtimes

resources/examples/Showtimes/blueprints/1.1/representations/Movie.apib

@@ -1,6 +1,6 @@
 ## Movie
 - `cast` (array[Person]) - Cast
-- `content_rating` (enum[string]) - MPAA rating
+- `content_rating`: `G` (enum[string]) - MPAA rating
     + Members
         + `G`
         + `NC-17`
@@ -20,6 +20,8 @@
 - `id` (number) - Unique ID
 - `kid_friendly` (boolean) - Kid friendly?
 - `name` (string) - Name
+- `purchase` (object)
+    - `url` (string) - URL to purchase the film.
 - `rotten_tomatoes_score` (number) - Rotten Tomatoes score
 - `runtime` (string) - Runtime
 - `showtimes` (array) - Non-theater specific showtimes

src/Exceptions/Representation/RestrictedFieldNameException.php

@@ -1,6 +1,8 @@
 <?php
 namespace Mill\Exceptions\Representation;
 
+use Mill\Parser\Representation\Documentation;
+
 class RestrictedFieldNameException extends \Exception
 {
     use RepresentationExceptionTrait;
@@ -13,7 +15,8 @@ class RestrictedFieldNameException extends \Exception
     public static function create($class, $method)
     {
         $message = sprintf(
-            '`__FIELD_DATA__` is a reserved `@api-field` name, and cannot be used in %s::%s.',
+            '`%s` is a reserved `@api-field` name, and cannot be used in %s::%s.',
+            Documentation::DOT_NOTATION_ANNOTATION_DATA_KEY,
             $class,
             $method
         );

src/Generator/Blueprint.php

@@ -8,6 +8,7 @@
 use Mill\Parser\Annotations\ScopeAnnotation;
 use Mill\Parser\Annotations\ThrowsAnnotation;
 use Mill\Parser\Annotations\UriSegmentAnnotation;
+use Mill\Parser\Representation\Documentation;
 use Mill\Parser\Resource\Action;
 
 class Blueprint extends Generator
@@ -399,9 +400,9 @@ private function processRepresentationFields($fields = [], $indent = 2)
             $blueprint .= $this->tab($indent);
 
             $data = [];
-            if (isset($field['__FIELD_DATA__'])) {
+            if (isset($field[Documentation::DOT_NOTATION_ANNOTATION_DATA_KEY])) {
                 /** @var array $data */
-                $data = $field['__FIELD_DATA__'];
+                $data = $field[Documentation::DOT_NOTATION_ANNOTATION_DATA_KEY];
                 $type = $this->convertTypeToCompatibleType(
                     $data['type'],
                     (isset($data['subtype'])) ? $data['subtype'] : false
@@ -440,9 +441,8 @@ private function processRepresentationFields($fields = [], $indent = 2)
             }
 
             // Process any exploded dot notation children of this field.
-            if (count($field) > 1) {
-                unset($field['__FIELD_DATA__']);
-
+            unset($field[Documentation::DOT_NOTATION_ANNOTATION_DATA_KEY]);
+            if (!empty($field)) {
                 // If this is an array, and has a subtype of object, we should indent a bit so we can properly render
                 // out the array objects.
                 if (!empty($data) && isset($data['subtype']) && $data['subtype'] === 'object') {

src/Parser/Annotation.php

@@ -449,6 +449,19 @@ public function getCapability()
         return $this->capability;
     }
 
+    /**
+     * Set a capability that this annotation requires. This is specifically used in tandem with representation depth
+     * parsing.
+     *
+     * @param string $capability
+     * @return Annotation
+     */
+    public function setCapability($capability)
+    {
+        $this->capability = $capability;
+        return $this;
+    }
+
     /**
      * Get the version constraint, if any, that this parameter is part of.
      *
@@ -460,8 +473,8 @@ public function getVersion()
     }
 
     /**
-     * Set a version that this annotation is available on. This is specifically used in tandem with `@api-see`
-     * annotations.
+     * Set a version that this annotation is available on. This is specifically used in tandem with representation
+     * depth parsing.
      *
      * @param Version $version
      * @return Annotation

src/Parser/Annotations/DataAnnotation.php

@@ -4,6 +4,7 @@
 use Mill\Exceptions\Representation\RestrictedFieldNameException;
 use Mill\Parser\Annotation;
 use Mill\Parser\MSON;
+use Mill\Parser\Representation\Documentation;
 
 /**
  * Handler for the `@api-data` annotation.
@@ -105,11 +106,16 @@ protected function parser()
         }
 
         if (!empty($parsed['identifier'])) {
-            if (strtoupper($parsed['identifier']) === '__FIELD_DATA__') {
+            if (strtoupper($parsed['identifier']) === Documentation::DOT_NOTATION_ANNOTATION_DATA_KEY) {
                 throw RestrictedFieldNameException::create($this->class, $this->method);
             }
         }
 
+        // If we have values present, but no sample data, set the sample as the first item in the values list.
+        if (!empty($parsed['values']) && empty($parsed['sample_data'])) {
+            $parsed['sample_data'] = array_keys($parsed['values'])[0];
+        }
+
         return $parsed;
     }
 

src/Parser/Representation/Documentation.php

@@ -13,6 +13,12 @@
  */
 class Documentation
 {
+    /**
+     * When building out dot-notation annotation keys for generating API Blueprint files (or any other generator),
+     * we use this key to designate the content of an annotations' data.
+     */
+    const DOT_NOTATION_ANNOTATION_DATA_KEY = '__FIELD_DATA__';
+
     /**
      * Name of the representation class that we're going to be parsing for documentation.
      *
@@ -175,7 +181,7 @@ public function getExplodedContentDotNotation()
         $arr = $this->toArray();
         foreach ($arr['content'] as $field => $data) {
             $content->set($field, [
-                '__FIELD_DATA__' => $data
+                self::DOT_NOTATION_ANNOTATION_DATA_KEY => $data
             ]);
         }