Merge pull request #83 from cnizzardini/feature/issue-57-schema-spec

Feature/issue 57 schema spec

Author: cnizzardini

README.md

@@ -329,12 +329,12 @@ class UsersController extends AppController {
 ```
 
 #### `@SwagEntity`
-Class level annotation for exposing entities to Swagger UI. By default all entities with routes will display as Swagger 
+Class level annotation for exposing entities to Swagger UI. By default, all entities with routes will display as Swagger 
 schema. You can hide a schema or display a schema that does not have an associated route.
 
 ```php
 /**
- * @Swag\SwagEntity(isVisible=false)
+ * @Swag\SwagEntity(isVisible=false, title="optional title", description="optional description")
  */
 class Employee extends Entity {
 ```
@@ -445,6 +445,46 @@ bin/cake bake controller {Name} --theme SwaggerBake
 - SwaggerBake has been developed primarily for application/json and application/x-www-form-urlencoded, but does have 
 some support for application/xml and *should* work with application/vnd.api+json.
 
+SwaggerBake does not document schema associations. If your application includes associations on things like 
+GET requests, you can easily add them into your swagger documentation through the OpenAPI `allOf` property. Since 
+SwaggerBake works in conjunction with OpenAPI YAML you can easily add a new schema with this association. Below is an 
+example of extending an existing City schema to include a Country association.
+
+```yaml
+# in your swagger.yml
+components:
+  schemas:
+    CityExtended:
+      description: 'City with extended information including Country'
+      type: object
+      allOf:
+        - $ref: '#/components/schemas/City'
+        - type: object
+          properties:
+            country:
+              $ref: '#/components/schemas/Country'
+
+```
+
+Then in your controller action you'd specify the Schema: 
+
+```php
+/**
+ * View method
+ * @Swag\SwagResponseSchema(refEntity="#/components/schemas/CityExtended")
+ */
+public function view($id)
+{
+    $this->request->allowMethod('get');
+    $city = $this->Cities->get($id, ['contain' => ['Countries']]);
+    $this->set(compact('cities'));
+    $this->viewBuilder()->setOption('serialize', 'cities');
+}
+```
+
+The demo application includes this and many other examples of usage. Read more about `oneOf`, `anyOf`, `allOf`, and 
+`not` in the [OpenAPI 3 documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/).
+
 ## Supported Versions
 
 This is built for CakePHP 4.x only. A cake-3.8 option is available, but not supported.

src/Lib/Annotation/SwagEntity.php

@@ -2,23 +2,32 @@
 
 namespace SwaggerBake\Lib\Annotation;
 
-use InvalidArgumentException;
-
 /**
  * @Annotation
  * @Target({"CLASS"})
  * @Attributes({
  *   @Attribute("isVisible", type="bool"),
+ *   @Attribute("title", type="string"),
+ *   @Attribute("description", type="string"),
  * })
  */
 class SwagEntity
 {
     /** @var bool  **/
     public $isVisible;
 
+    /** @var string|null */
+    public $title;
+
+    /** @var string|null */
+    public $description;
+
     public function __construct(array $values)
     {
-        $values = array_merge(['isVisible' => true], $values);
-        $this->isVisible = (bool) $values['isVisible'];
+        foreach ($values as $attribute => $value) {
+            if (property_exists($this, $attribute)) {
+                $this->{$attribute} = $value;
+            }
+        }
     }
 }

src/Lib/OpenApi/Schema.php

@@ -14,8 +14,11 @@ class Schema implements JsonSerializable
     /** @var string */
     private $name = '';
 
-    /** @var string */
-    private $description = '';
+    /** @var string|null */
+    private $title;
+
+    /** @var string|null */
+    private $description;
 
     /** @var string */
     private $type = '';
@@ -38,6 +41,9 @@ class Schema implements JsonSerializable
     /** @var array  */
     private $allOf = [];
 
+    /** @var array  */
+    private $not = [];
+
     /** @var array  */
     private $enum = [];
 
@@ -51,6 +57,7 @@ public function toArray() : array
     {
         $vars = get_object_vars($this);
         unset($vars['name']);
+
         if (empty($vars['required'])) {
             unset($vars['required']);
         } else {
@@ -59,8 +66,8 @@ public function toArray() : array
         }
 
         // remove empty properties to avoid swagger.json clutter
-        foreach (['properties', 'items', 'oneOf', 'anyOf', 'allOf', 'enum', 'format', 'type'] as $v) {
-            if (empty($vars[$v])) {
+        foreach (['title','description','properties','items','oneOf','anyOf','allOf','not','enum','format','type'] as $v) {
+            if (empty($vars[$v]) || is_null($vars[$v])) {
                 unset($vars[$v]);
             }
         }
@@ -94,6 +101,24 @@ public function setName(string $name): Schema
         return $this;
     }
 
+    /**
+     * @return string|null
+     */
+    public function getTitle(): ?string
+    {
+        return $this->title;
+    }
+
+    /**
+     * @param string|null $title
+     * @return Schema
+     */
+    public function setTitle(?string $title): Schema
+    {
+        $this->title = $title;
+        return $this;
+    }
+
     /**
      * @return string
      */
@@ -180,18 +205,18 @@ public function pushProperty(SchemaProperty $property): Schema
     }
 
     /**
-     * @return string
+     * @return string|null
      */
-    public function getDescription(): string
+    public function getDescription(): ?string
     {
         return $this->description;
     }
 
     /**
-     * @param string $description
+     * @param string|null $description
      * @return Schema
      */
-    public function setDescription(string $description): Schema
+    public function setDescription(?string $description): Schema
     {
         $this->description = $description;
         return $this;
@@ -269,6 +294,24 @@ public function setAllOf(array $allOf): Schema
         return $this;
     }
 
+    /**
+     * @return array
+     */
+    public function getNot(): array
+    {
+        return $this->not;
+    }
+
+    /**
+     * @param array $not
+     * @return Schema
+     */
+    public function setNot(array $not): Schema
+    {
+        $this->not = $not;
+        return $this;
+    }
+
     /**
      * @return array
      */

src/Lib/Schema/SchemaFactory.php

@@ -40,7 +40,9 @@ public function __construct(Configuration $config)
      */
     public function create(EntityDecorator $entity) : ?Schema
     {
-        if (!$this->isSwaggable($entity)) {
+        $swagEntity = $this->getSwagEntityAnnotation($entity);
+
+        if ($swagEntity !== null && $swagEntity->isVisible === false) {
             return null;
         }
 
@@ -50,14 +52,19 @@ public function create(EntityDecorator $entity) : ?Schema
 
         $properties = $this->getProperties($entity);
 
-        $schema = new Schema();
-        $schema
+        $schema = (new Schema())
             ->setName($entity->getName())
-            ->setDescription($docBlock ? $docBlock->getSummary() : '')
+            ->setTitle($swagEntity !== null ? $swagEntity->description : null)
             ->setType('object')
             ->setProperties($properties)
         ;
 
+        if ($swagEntity !== null && isset($swagEntity->description)) {
+            $schema->setDescription($swagEntity->description);
+        } else {
+            $schema->setDescription($docBlock ? $docBlock->getSummary() : null);
+        }
+
         $requiredProperties = array_filter($properties, function ($property) {
             return $property->isRequired();
         });
@@ -166,20 +173,22 @@ private function getSwagPropertyAnnotations(EntityDecorator $entity) : array
     }
 
     /**
+     * Returns instance of SwagEntity annotation, otherwise null
+     *
      * @param EntityDecorator $entity
-     * @return bool
+     * @return SwagEntity|null
      */
-    private function isSwaggable(EntityDecorator $entity) : bool
+    private function getSwagEntityAnnotation(EntityDecorator $entity) : ?SwagEntity
     {
         $annotations = AnnotationUtility::getClassAnnotationsFromInstance($entity->getEntity());
 
         foreach ($annotations as $annotation) {
             if ($annotation instanceof SwagEntity) {
-                return $annotation->isVisible;
+                return $annotation;
             }
         }
 
-        return true;
+        return null;
     }
 
     /**

tests/TestCase/Lib/Operation/OperationResponseTest.php

@@ -140,9 +140,9 @@ public function testAddOperationWithNoResponseDefined()
         $this->assertNotEmpty($response);
 
         $content = $response->getContentByMimeType('application/json');
+
         $this->assertNotEmpty($content);
         $this->assertNotEmpty($content->getSchema());
-        $this->assertCount(1, $content->getSchema()->toArray());
     }
 
     public function testDeleteActionResponseWithHttp204()
@@ -191,6 +191,5 @@ public function testNoResponseDefined()
         $content = $response->getContentByMimeType('application/json');
         $this->assertNotEmpty($content);
         $this->assertNotEmpty($content->getSchema());
-        $this->assertCount(1, $content->getSchema()->toArray());
     }
 }