Merge pull request #25 from cnizzardini/branch/v1.0.2

Branch/v1.0.2

README.md

@@ -70,7 +70,9 @@ build the following from your existing routes and models without additional effo
     - Sub resources
 - Schema
 
-SwaggerBake works with your existing YML definitions and will not overwrite anything.
+SwaggerBake works with your existing YML definitions and will not overwrite anything. By default, it uses 
+components > schemas > Exception as your Swagger documentations Exception schema. See the default 
+[swagger.yml](assets/swagger.yml) and `exceptionSchema` in [swagger_bake.php](assets/swagger_bake.php) for more info.
 
 ## Doc Blocks
 
@@ -123,7 +125,7 @@ Method level annotation for adding query parameters.
 
 ```php
 /**
- * @Swag\SwagQuery(name="queryParamName", type="string", required=false)
+ * @Swag\SwagQuery(name="queryParamName", type="string", description="string", required=false)
  */
 public function index() {}
 ```
@@ -133,7 +135,7 @@ Method level annotation for adding form data fields.
 
 ```php
 /**
- * @Swag\SwagForm(name="fieldName", type="string", required=false)
+ * @Swag\SwagForm(name="fieldName", type="string", description="string", required=false)
  */
 public function index() {}
 ```
@@ -143,7 +145,7 @@ Method level annotation for adding header parameters.
 
 ```php
 /**
- * @Swag\SwagHeader(name="X-HEAD-ATTRIBUTE", type="string", required=false)
+ * @Swag\SwagHeader(name="X-HEAD-ATTRIBUTE", type="string", description="string", required=false)
  */
 public function index() {}
 ```
@@ -183,8 +185,7 @@ Method level annotation for describing custom content in request body.
 
 ```php
 /**
- * @Swag\SwagRequestBodyContent(refEntity="#/components/schemas/Lead", mimeType="application/x-www-form-urlencoded")
- * @Swag\SwagRequestBodyContent(refEntity="", mimeType="text/plain")
+ * @Swag\SwagRequestBodyContent(refEntity="#/components/schemas/Lead", mimeType="application/json")
  */
 public function index() {}
 ```
@@ -225,7 +226,7 @@ Class level annotation for customizing Schema Attributes with @SwagEntityAttribu
 
 ```php
 /**
- * @Swag\SwagEntityAttribute(name="modified", type="string", readOnly=true, required=false)
+ * @Swag\SwagEntityAttribute(name="modified", type="string", description="string", readOnly=true, required=false)
  */
 class Employee extends Entity {
 ```
@@ -343,6 +344,11 @@ paths using CakePHPs route resource functionality. Read the
 [Cake Routing documentation](https://book.cakephp.org/4/en/development/routing.html) which describes in detail how to 
 add, remove, modify, and alter routes. 
 
+#### Missing CSRF token body
+
+Either disable CSRF protection on your main route in `config/routes.php` or enable CSRF protection in Swagger 
+UI. The library does not currently support adding this in for you.
+
 ## Reporting Issues
 
 This is a new library so please take some steps before reporting issues. You can copy & paste the JSON SwaggerBake 

assets/swagger.yml

@@ -9,3 +9,18 @@ servers:
 paths:
 
 definitions:
+
+components:
+  schemas:
+    Exception:
+      type: object
+      properties:
+        code:
+          type: integer
+          example: 500
+        url:
+          type: string
+          example: /url/path
+        message:
+          type: string
+          example: Internal Error

assets/swagger_bake.php

@@ -13,6 +13,8 @@
  *
  * @var string $docType: Options are swagger and redoc, defaults: swagger
  *
+ * @var string $exceptionSchema: The name of your Exception schema in your swagger.yml definition file.
+ *
  * @var array $namespaces: Can be used if your controllers or entities exist in non-standard namespace such as a plugin
  */
 return [
@@ -21,13 +23,17 @@
         'yml' => '/config/swagger.yml',
         'json' => '/webroot/swagger.json',
         'webPath' => '/swagger.json',
-        'hotReload' => false,
+        'hotReload' => \Cake\Core\Configure::read('debug'),
+        /** optional configurations below:  **/
+        /*
         'docType' => 'swagger',
+        'exceptionSchema' => 'Exception',
         'namespaces' => [
             'controllers' => ['\App\\'],
             'entities' => ['\App\\'],
             'tables' => ['\App\\']
         ]
+        */
     ]
 ];
 

src/Command/ModelCommand.php

@@ -25,7 +25,9 @@ class ModelCommand extends Command
      */
     public function execute(Arguments $args, ConsoleIo $io)
     {
-        $io->out("Running...");
+        $io->hr();
+        $io->out("| SwaggerBake is checking your models...");
+        $io->hr();
 
         ValidateConfiguration::validate();
 
@@ -36,7 +38,11 @@ public function execute(Arguments $args, ConsoleIo $io)
         $models = $cakeModel->getModels();
 
         if (empty($models)) {
-            return $io->warning('No models found');
+            $io->out();
+            $io->warning('No models were found that are associated with: ' . $config->getPrefix());
+            $io->out("Have you added RESTful routes? Do you have models associated with those routes?");
+            $io->out();
+            return;
         }
 
         $header = ['Attribute','Data Type', 'Swagger Type','Default','Primary Key'];

src/Command/RouteCommand.php

@@ -25,12 +25,14 @@ class RouteCommand extends Command
      */
     public function execute(Arguments $args, ConsoleIo $io)
     {
-        $io->out("Running...");
+        $io->hr();
+        $io->out("| SwaggerBake is checking your routes...");
+        $io->hr();
 
         ValidateConfiguration::validate();
 
         $output = [
-            ['Route name', 'URI template', 'Defaults'],
+            ['Route name', 'URI template', 'Method(s)', 'Controller', 'Action', 'Plugin'],
         ];
 
         $config = new Configuration();
@@ -39,15 +41,22 @@ public function execute(Arguments $args, ConsoleIo $io)
         $routes = $cakeRoute->getRoutes();
 
         if (empty($routes)) {
-            $io->out("<warning>No routes were found for: $prefix</warning>");
-            $io->out('<info>https://book.cakephp.org/4/en/development/routing.html#restful-routing</info>');
+            $io->out();
+            $io->warning("No routes were found for: $prefix");
+            $io->out("Have you added RESTful routes? Do you have models associated with those routes?");
+            $io->out();
             return;
         }
 
         foreach ($routes as $route) {
-            $name = $route->options['_name'] ?? $route->getName();
-            ksort($route->defaults);
-            $output[] = [$name, $route->template, json_encode($route->defaults)];
+            $output[] = [
+                $route->getName(),
+                $route->getTemplate(),
+                implode(', ', $route->getMethods()),
+                $route->getController(),
+                $route->getAction(),
+                $route->getPlugin(),
+            ];
         }
 
         $io->helper('table')->output($output);

src/Lib/AbstractParameter.php

@@ -2,10 +2,10 @@
 
 namespace SwaggerBake\Lib;
 
-use Cake\Routing\Route\Route;
 use Doctrine\Common\Annotations\AnnotationReader;
 use ReflectionClass;
 use SwaggerBake\Lib\Exception\SwaggerBakeRunTimeException;
+use SwaggerBake\Lib\Model\ExpressiveRoute;
 
 class AbstractParameter
 {
@@ -18,14 +18,13 @@ class AbstractParameter
     protected $reflectionMethods;
     protected $config;
 
-    public function __construct(Route $route, Configuration $config)
+    public function __construct(ExpressiveRoute $route, Configuration $config)
     {
         $this->config = $config;
         $this->route = $route;
 
-        $defaults = (array) $this->route->defaults;
-        $this->actionName = $defaults['action'];
-        $this->className = $defaults['controller'] . 'Controller';
+        $this->actionName = $this->route->getAction();
+        $this->className = $this->route->getController() . 'Controller';
 
         $this->controller = $this->getControllerFromNamespaces($this->className);
         $instance = new $this->controller;

src/Lib/Annotation/SwagEntity.php

@@ -13,6 +13,7 @@
  */
 class SwagEntity
 {
+    /** @var bool  **/
     public $isVisible;
 
     public function __construct(array $values)

src/Lib/Annotation/SwagEntityAttribute.php

@@ -10,17 +10,30 @@
  * @Attributes({
  *   @Attribute("name", type = "string"),
  *   @Attribute("type",  type = "string"),
+ *   @Attribute("description",  type = "string"),
  *   @Attribute("readOnly",  type = "bool"),
  *   @Attribute("writeOnly",  type = "bool"),
  *   @Attribute("required",  type = "bool"),
  * })
  */
 class SwagEntityAttribute
 {
+    /** @var string */
     public $name;
+
+    /** @var string */
     public $type;
+
+    /** @var string */
+    public $description;
+
+    /** @var bool */
     public $readOnly;
+
+    /** @var bool */
     public $writeOnly;
+
+    /** @var bool */
     public $required;
 
     public function __construct(array $values)
@@ -30,12 +43,13 @@ public function __construct(array $values)
         }
 
         $values = array_merge(
-            ['type' => 'string', 'readOnly' => false, 'writeOnly' => false, 'required' => false],
+            ['type' => 'string', 'description' => '', 'readOnly' => false, 'writeOnly' => false, 'required' => false],
             $values
         );
 
         $this->name = $values['name'];
         $this->type = $values['type'];
+        $this->description = $values['description'];
         $this->readOnly = $values['readOnly'];
         $this->writeOnly = $values['writeOnly'];
         $this->required = $values['required'];

src/Lib/Annotation/SwagEntityAttributeHandler.php

@@ -11,6 +11,7 @@ public function getSchemaProperty(SwagEntityAttribute $annotation) : SchemaPrope
         $schemaProperty = new SchemaProperty();
         $schemaProperty
             ->setName($annotation->name)
+            ->setDescription($annotation->description)
             ->setType($annotation->type)
             ->setReadOnly($annotation->readOnly)
             ->setWriteOnly($annotation->writeOnly)

src/Lib/Annotation/SwagForm.php

@@ -12,13 +12,22 @@
  * @Attributes({
  *   @Attribute("name", type = "string"),
  *   @Attribute("type",  type = "string"),
- *   @Attribute("required",  type = "bool"),
+ *   @Attribute("description",  type="string"),
+ *   @Attribute("required",  type="boolean"),
  * })
  */
 class SwagForm
 {
+    /** @var string */
     public $name;
+
+    /** @var string */
     public $type;
+
+    /** @var string */
+    public $description;
+
+    /** @var bool */
     public $required;
 
     public function __construct(array $values)
@@ -27,7 +36,7 @@ public function __construct(array $values)
             throw new InvalidArgumentException('Name parameter is required');
         }
 
-        $values = array_merge(['type' => 'string', 'required' => false], $values);
+        $values = array_merge(['type' => 'string', 'description' => '', 'required' => false], $values);
 
         if (!in_array($values['type'], OpenApiDataType::TYPES)) {
             $type = $values['type'];
@@ -42,6 +51,7 @@ public function __construct(array $values)
 
         $this->name = $values['name'];
         $this->type = $values['type'];
-        $this->required = $values['required'];
+        $this->description = $values['description'];
+        $this->required = (bool) $values['required'];
     }
 }

src/Lib/Annotation/SwagFormHandler.php

@@ -10,6 +10,7 @@ public function getSchemaProperty(SwagForm $annotation) : SchemaProperty
     {
         $schemaProperty = new SchemaProperty();
         $schemaProperty
+            ->setDescription($annotation->description)
             ->setName($annotation->name)
             ->setType($annotation->type)
             ->setRequired($annotation->required)

src/Lib/Annotation/SwagHeader.php

@@ -10,13 +10,22 @@
  * @Attributes({
  *   @Attribute("name", type = "string"),
  *   @Attribute("type",  type = "string"),
+ *   @Attribute("description",  type = "string"),
  *   @Attribute("required",  type = "bool"),
  * })
  */
 class SwagHeader
 {
+    /** @var string */
     public $name;
+
+    /** @var string */
     public $type;
+
+    /** @var string */
+    public $description;
+
+    /** @var bool */
     public $required;
 
     public function __construct(array $values)
@@ -25,10 +34,11 @@ public function __construct(array $values)
             throw new InvalidArgumentException('Name parameter is required');
         }
 
-        $values = array_merge(['type' => 'string', 'required' => false], $values);
+        $values = array_merge(['type' => 'string', 'description' => '', 'required' => false], $values);
 
         $this->name = $values['name'];
         $this->type = $values['type'];
-        $this->required = $values['required'];
+        $this->description = $values['description'];
+        $this->required = (bool) $values['required'];
     }
 }

src/Lib/Annotation/SwagHeaderHandler.php

@@ -12,6 +12,7 @@ public function getHeaderParameters(SwagHeader $annotation) : Parameter
         $parameter = new Parameter();
         $parameter
             ->setName($annotation->name)
+            ->setDescription($annotation->description)
             ->setAllowEmptyValue(false)
             ->setDeprecated(false)
             ->setRequired($annotation->required)

src/Lib/Annotation/SwagOperation.php

@@ -13,6 +13,7 @@
  */
 class SwagOperation
 {
+    /** @var bool */
     public $isVisible;
 
     public function __construct(array $values)

src/Lib/Annotation/SwagPath.php

@@ -13,6 +13,7 @@
  */
 class SwagPath
 {
+    /** @var bool */
     public $isVisible;
 
     public function __construct(array $values)