Moving param and uriSegment annotations over to a new MSON syntax. #42

erunion · Apr 28, 2017 · 3bcfe6d · 3bcfe6d
1 parent be36f8f
commit 3bcfe6d
Show file tree

Hide file tree

Showing 20 changed files with 795 additions and 354 deletions.
diff --git a/composer.json b/composer.json
@@ -21,7 +21,8 @@
         "symfony/console": "^2.8",
         "pimple/pimple": "^3.0",
         "league/flysystem": "^1.0",
-        "composer/semver": "^1.4"
+        "composer/semver": "^1.4",
+        "gossi/docblock": "^1.5"
     },
     "require-dev": {
         "squizlabs/php_codesniffer": "^2.7",

diff --git a/resources/examples/Showtimes/Controllers/Movie.php b/resources/examples/Showtimes/Controllers/Movie.php
@@ -14,7 +14,7 @@ class Movie
      * @api-label Get a single movie.
      *
      * @api-uri:public {Movies} /movies/+id
-     * @api-uriSegment {/movies/+id} {integer} id Movie ID
+     * @api-uriSegment {/movies/+id} id (integer) - Movie ID
      *
      * @api-contentType application/json
      *
@@ -34,22 +34,31 @@ public function GET()
      * @api-label Update a movie.
      *
      * @api-uri:public {Movies} /movies/+id
-     * @api-uriSegment {/movies/+id} {integer} id Movie ID
+     * @api-uriSegment {/movies/+id} id (integer) - Movie ID
      *
      * @api-contentType application/json
      * @api-scope edit
      * @api-minVersion 1.1
      *
-     * @api-param:public {string} name Name of the movie.
-     * @api-param:public {string} description Description, or tagline, for the movie.
-     * @api-param:public {string} runtime (optional) Movie runtime, in `HHhr MMmin` format.
-     * @api-param:public {string} content_rating [G|PG|PG-13|R|NC-17|X|NR|UR] (optional) MPAA rating
-     * @api-param:public {array} genres (optional) Array of movie genres.
-     * @api-param:public {string} trailer (optional) Trailer URL
-     * @api-param:public {string} director (optional) Name of the director.
-     * @api-param:public {array} cast (optional) Array of names of the cast.
-     * @api-param:public {boolean} is_kid_friendly (optional) Is this movie kid friendly?
-     * @api-param:public {integer} rotten_tomatoes_score (optional) Rotten Tomatoes score
+     * @api-param:public name (string, required) - Name of the movie.
+     * @api-param:public description (string, required) - Description, or tagline, for the movie.
+     * @api-param:public runtime (string, optional) - Movie runtime, in `HHhr MMmin` format.
+     * @api-param:public content_rating (string, optional) - MPAA rating
+     *  + Members
+     *      - `G`
+     *      - `PG`
+     *      - `PG-13`
+     *      - `R`
+     *      - `NC-17`
+     *      - `X`
+     *      - `NR`
+     *      - `UR`
+     * @api-param:public genres (array, optional) - Array of movie genres.
+     * @api-param:public trailer (string, optional) - Trailer URL
+     * @api-param:public director (string, optional) - Name of the director.
+     * @api-param:public cast (array, optional) - Array of names of the cast.
+     * @api-param:public is_kid_friendly (boolean, optional) - Is this movie kid friendly?
+     * @api-param:public rotten_tomatoes_score (integer, optional) - Rotten Tomatoes score
      *
      * @api-return:public {object} \Mill\Examples\Showtimes\Representations\Movie
      *
@@ -59,7 +68,7 @@ public function GET()
      * @api-throws:public {404} \Mill\Examples\Showtimes\Representations\Error If the movie could not be found.
      *
      * @api-version >=1.1.1
-     * @api-param:public {string} imdb (optional) IMDB URL
+     * @api-param:public imdb (string, optional) - IMDB URL
      */
     public function PATCH()
     {
@@ -72,7 +81,7 @@ public function PATCH()
      * @api-label Delete a movie.
      *
      * @api-uri:private {Movies} /movies/+id
-     * @api-uriSegment {/movies/+id} {integer} id Movie ID
+     * @api-uriSegment {/movies/+id} id (integer) - Movie ID
      *
      * @api-contentType application/json
      * @api-scope delete

diff --git a/resources/examples/Showtimes/Controllers/Movies.php b/resources/examples/Showtimes/Controllers/Movies.php
@@ -15,7 +15,7 @@ class Movies
      *
      * @api-contentType application/json
      *
-     * @api-param:public {string} location Location you want movies for.
+     * @api-param:public location (string) - Location you want movies for.
      *
      * @api-return:public {collection} \Mill\Examples\Showtimes\Representations\Movie
      *
@@ -36,15 +36,24 @@ public function GET()
      * @api-contentType application/json
      * @api-scope create
      *
-     * @api-param:public {string} name Name of the movie.
-     * @api-param:public {string} description Description, or tagline, for the movie.
-     * @api-param:public {string} runtime (optional) Movie runtime, in `HHhr MMmin` format.
-     * @api-param:public {string} content_rating [G|PG|PG-13|R|NC-17|X|NR|UR] (optional) MPAA rating
-     * @api-param:public {array} genres (optional) Array of movie genres.
-     * @api-param:public {string} director (optional) Name of the director.
-     * @api-param:public {array} cast (optional) Array of names of the cast.
-     * @api-param:public {boolean} is_kid_friendly (optional) Is this movie kid friendly?
-     * @api-param:public {integer} rotten_tomatoes_score (optional) Rotten Tomatoes score
+     * @api-param:public name (string, required) - Name of the movie.
+     * @api-param:public name (string, required) - Description, or tagline, for the movie.
+     * @api-param:public runtime (string, optional) - Movie runtime, in `HHhr MMmin` format.
+     * @api-param:public content_rating (string, optional) - MPAA rating
+     *  + Members
+     *      - `G`
+     *      - `PG`
+     *      - `PG-13`
+     *      - `R`
+     *      - `NC-17`
+     *      - `X`
+     *      - `NR`
+     *      - `UR`
+     * @api-param:public genres (array, optional) - Array of movie genres.
+     * @api-param:public director (string, optional) - Name of the director.
+     * @api-param:public cast (array, optional) - Array of names of the cast.
+     * @api-param:public is_kid_friendly (boolean, optional) - Is this movie kid friendly?
+     * @api-param:public rotten_tomatoes_score (integer, optional) - Rotten Tomatoes score
      *
      * @api-return:public {object} \Mill\Examples\Showtimes\Representations\Movie
      *
@@ -53,8 +62,8 @@ public function GET()
      * @api-throws:public {400} \Mill\Examples\Showtimes\Representations\Error If the IMDB URL could not be validated.
      *
      * @api-version >=1.1
-     * @api-param:public {string} imdb (optional) IMDB URL
-     * @api-param:public {string} trailer (optional) Trailer URL
+     * @api-param:public imdb (string, optional) - IMDB URL
+     * @api-param:public trailer (string, optional) - Trailer URL
      */
     public function POST()
     {

diff --git a/resources/examples/Showtimes/Controllers/Theater.php b/resources/examples/Showtimes/Controllers/Theater.php
@@ -14,7 +14,7 @@ class Theater
      * @api-label Get a single movie theater
      *
      * @api-uri:public {Theaters} /theaters/+id
-     * @api-uriSegment {/theaters/+id} {integer} id Theater ID
+     * @api-uriSegment {/theaters/+id} id (integer) - Theater ID
      *
      * @api-contentType application/json
      *
@@ -35,14 +35,14 @@ public function GET()
      * @api-label Update a movie theater
      *
      * @api-uri:public {Theaters} /theaters/+id
-     * @api-uriSegment {/theaters/+id} {integer} id Theater ID
+     * @api-uriSegment {/theaters/+id} id (integer) - Theater ID
      *
      * @api-contentType application/json
      * @api-scope create
      *
-     * @api-param:public {string} name Name of the theater.
-     * @api-param:public {string} address Theater address
-     * @api-param:public {string} phone_number Theater phone number
+     * @api-param:public name (string, required) - Name of the theater.
+     * @api-param:public address (string, required) - Theater address
+     * @api-param:public phone_number (string, required) - Theater phone number
      *
      * @api-return:public {object} \Mill\Examples\Showtimes\Representations\Theater
      *
@@ -62,7 +62,7 @@ public function PATCH()
      * @api-label Delete a movie movie.
      *
      * @api-uri:private {Theaters} /theaters/+id
-     * @api-uriSegment {/theaters/+id} {integer} id Theater ID
+     * @api-uriSegment {/theaters/+id} id (integer) - Theater ID
      *
      * @api-contentType application/json
      * @api-scope delete

diff --git a/resources/examples/Showtimes/Controllers/Theaters.php b/resources/examples/Showtimes/Controllers/Theaters.php
@@ -15,7 +15,7 @@ class Theaters
      *
      * @api-contentType application/json
      *
-     * @api-param:public {string} location Location you want theaters in.
+     * @api-param:public location (string, required) - Location you want theaters in.
      *
      * @api-return:public {collection} \Mill\Examples\Showtimes\Representations\Theater
      *
@@ -36,9 +36,9 @@ public function GET()
      * @api-contentType application/json
      * @api-scope create
      *
-     * @api-param:public {string} name Name of the theater.
-     * @api-param:public {string} address Theater address
-     * @api-param:public {string} phone_number Theater phone number
+     * @api-param:public name (string, required) - Name of the theater.
+     * @api-param:public address (string, required) - Theater address
+     * @api-param:public phone_number (string, required) - Theater phone number
      *
      * @api-return:public {object} \Mill\Examples\Showtimes\Representations\Theater
      *

diff --git a/src/Exceptions/Resource/Annotations/InvalidMSONSyntaxException.php b/src/Exceptions/Resource/Annotations/InvalidMSONSyntaxException.php
@@ -0,0 +1,34 @@
+<?php
+namespace Mill\Exceptions\Resource\Annotations;
+
+class InvalidMSONSyntaxException extends \Exception
+{
+    use AnnotationExceptionTrait;
+
+    /**
+     * @param string $annotation
+     * @param string $docblock
+     * @param string $class
+     * @param string $method
+     * @return InvalidMSONSyntaxException
+     */
+    public static function create($required_field, $annotation, $docblock, $class, $method)
+    {
+        $message = sprintf(
+            'Unable to parse a `%s` in the MSON on %s::%s for: `@api-%s %s`',
+            $required_field,
+            $class,
+            $method,
+            $annotation,
+            $docblock
+        );
+
+        $exception = new self($message);
+        $exception->annotation = $annotation;
+        $exception->docblock = $docblock;
+        $exception->class = $class;
+        $exception->method = $method;
+
+        return $exception;
+    }
+}
diff --git a/src/Exceptions/Resource/Annotations/UnsupportedTypeException.php b/src/Exceptions/Resource/Annotations/UnsupportedTypeException.php
@@ -14,7 +14,7 @@ class UnsupportedTypeException extends \Exception
     public static function create($annotation, $class, $method)
     {
         $message = sprintf(
-            'The type on `@api-param %s`in %s::%s is unsupported. Please check the documentation for supported types.',
+            'The type on `@api-param %s` in %s::%s is unsupported. Please check the documentation for supported types.',
             $annotation,
             $class,
             $method