Merge pull request #1575 from FilipBenco/master

Extensible property describing

ModelDescriber/ObjectModelDescriber.php

@@ -17,6 +17,7 @@ use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareInterface;
 use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareTrait;
 use Nelmio\ApiDocBundle\Model\Model;
 use Nelmio\ApiDocBundle\ModelDescriber\Annotations\AnnotationsReader;
+use Nelmio\ApiDocBundle\PropertyDescriber\PropertyDescriberInterface;
 use Symfony\Component\PropertyInfo\PropertyInfoExtractorInterface;
 use Symfony\Component\PropertyInfo\Type;
 
@@ -24,17 +25,23 @@ class ObjectModelDescriber implements ModelDescriberInterface, ModelRegistryAwar
 {
     use ModelRegistryAwareTrait;
 
+    /** @var PropertyInfoExtractorInterface */
     private $propertyInfo;
+    /** @var Reader */
     private $doctrineReader;
+    /** @var PropertyDescriberInterface[] */
+    private $propertyDescribers;
 
     private $swaggerDefinitionAnnotationReader;
 
     public function __construct(
         PropertyInfoExtractorInterface $propertyInfo,
-        Reader $reader
+        Reader $reader,
+        $propertyDescribers
     ) {
         $this->propertyInfo = $propertyInfo;
         $this->doctrineReader = $reader;
+        $this->propertyDescribers = $propertyDescribers;
     }
 
     public function describe(Model $model, Schema $schema)
@@ -86,40 +93,24 @@ class ObjectModelDescriber implements ModelDescriberInterface, ModelRegistryAwar
             }
 
             $type = $types[0];
-            if ($type->isCollection()) {
-                $type = $type->getCollectionValueType();
-                if (null === $type) {
-                    throw new \LogicException(sprintf('Property "%s:%s" is an array, but its items type isn\'t specified. You can specify that by using the type `string[]` for instance or `@SWG\Property(type="array", @SWG\Items(type="string"))`.', $class, $propertyName));
-                }
+            $this->describeProperty($type, $model, $property, $propertyName);
+        }
+    }
 
-                $property->setType('array');
-                $property = $property->getItems();
+    private function describeProperty(Type $type, Model $model, Schema $property, string $propertyName)
+    {
+        foreach ($this->propertyDescribers as $propertyDescriber) {
+            if ($propertyDescriber instanceof ModelRegistryAwareInterface) {
+                $propertyDescriber->setModelRegistry($this->modelRegistry);
             }
+            if ($propertyDescriber->supports($type)) {
+                $propertyDescriber->describe($type, $property, $model->getGroups());
 
-            if (Type::BUILTIN_TYPE_STRING === $type->getBuiltinType()) {
-                $property->setType('string');
-            } elseif (Type::BUILTIN_TYPE_BOOL === $type->getBuiltinType()) {
-                $property->setType('boolean');
-            } elseif (Type::BUILTIN_TYPE_INT === $type->getBuiltinType()) {
-                $property->setType('integer');
-            } elseif (Type::BUILTIN_TYPE_FLOAT === $type->getBuiltinType()) {
-                $property->setType('number');
-                $property->setFormat('float');
-            } elseif (Type::BUILTIN_TYPE_OBJECT === $type->getBuiltinType()) {
-                if (is_a($type->getClassName(), \DateTimeInterface::class, true)) {
-                    $property->setType('string');
-                    $property->setFormat('date-time');
-                } else {
-                    $type = new Type($type->getBuiltinType(), false, $type->getClassName(), $type->isCollection(), $type->getCollectionKeyType(), $type->getCollectionValueType()); // ignore nullable field
-
-                    $property->setRef(
-                        $this->modelRegistry->register(new Model($type, $model->getGroups()))
-                    );
-                }
-            } else {
-                throw new \Exception(sprintf('Type "%s" is not supported in %s::$%s. You may use the `@SWG\Property(type="")` annotation to specify it manually.', $type->getBuiltinType(), $class, $propertyName));
+                return;
             }
         }
+
+        throw new \Exception(sprintf('Type "%s" is not supported in %s::$%s. You may use the `@SWG\Property(type="")` annotation to specify it manually.', $type->getBuiltinType(), $model->getType()->getClassName(), $propertyName));
     }
 
     public function supports(Model $model): bool

PropertyDescriber/ArrayPropertyDescriber.php

@@ -0,0 +1,57 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\PropertyDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareInterface;
+use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareTrait;
+use Symfony\Component\PropertyInfo\Type;
+
+class ArrayPropertyDescriber implements PropertyDescriberInterface, ModelRegistryAwareInterface
+{
+    use ModelRegistryAwareTrait;
+
+    /** @var PropertyDescriberInterface[] */
+    private $propertyDescribers;
+
+    public function __construct(iterable $propertyDescribers = [])
+    {
+        $this->propertyDescribers = $propertyDescribers;
+    }
+
+    public function describe(Type $type, Schema $property, array $groups = null)
+    {
+        $type = $type->getCollectionValueType();
+        if (null === $type) {
+            throw new \LogicException(sprintf('Property "%s:%s" is an array, but its items type isn\'t specified. You can specify that by using the type `string[]` for instance or `@SWG\Property(type="array", @SWG\Items(type="string"))`.', $class, $propertyName));
+        }
+
+        $property->setType('array');
+        $property = $property->getItems();
+
+        foreach ($this->propertyDescribers as $propertyDescriber) {
+            if ($propertyDescriber instanceof ModelRegistryAwareInterface) {
+                $propertyDescriber->setModelRegistry($this->modelRegistry);
+            }
+            if ($propertyDescriber->supports($type)) {
+                $propertyDescriber->describe($type, $property, $groups);
+
+                break;
+            }
+        }
+    }
+
+    public function supports(Type $type): bool
+    {
+        return $type->isCollection();
+    }
+}

PropertyDescriber/BooleanPropertyDescriber.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\PropertyDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use Symfony\Component\PropertyInfo\Type;
+
+class BooleanPropertyDescriber implements PropertyDescriberInterface
+{
+    public function describe(Type $type, Schema $property, array $groups = null)
+    {
+        $property->setType('boolean');
+    }
+
+    public function supports(Type $type): bool
+    {
+        return Type::BUILTIN_TYPE_BOOL === $type->getBuiltinType();
+    }
+}

PropertyDescriber/DateTimePropertyDescriber.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\PropertyDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use Symfony\Component\PropertyInfo\Type;
+
+class DateTimePropertyDescriber implements PropertyDescriberInterface
+{
+    public function describe(Type $type, Schema $property, array $groups = null)
+    {
+        $property->setType('string');
+        $property->setFormat('date-time');
+    }
+
+    public function supports(Type $type): bool
+    {
+        return Type::BUILTIN_TYPE_OBJECT === $type->getBuiltinType()
+            && is_a($type->getClassName(), \DateTimeInterface::class, true);
+    }
+}

PropertyDescriber/FloatPropertyDescriber.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\PropertyDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use Symfony\Component\PropertyInfo\Type;
+
+class FloatPropertyDescriber implements PropertyDescriberInterface
+{
+    public function describe(Type $type, Schema $property, array $groups = null)
+    {
+        $property->setType('number');
+        $property->setFormat('float');
+    }
+
+    public function supports(Type $type): bool
+    {
+        return Type::BUILTIN_TYPE_FLOAT === $type->getBuiltinType();
+    }
+}

PropertyDescriber/IntegerPropertyDescriber.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\PropertyDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use Symfony\Component\PropertyInfo\Type;
+
+class IntegerPropertyDescriber implements PropertyDescriberInterface
+{
+    public function describe(Type $type, Schema $property, array $groups = null)
+    {
+        $property->setType('integer');
+    }
+
+    public function supports(Type $type): bool
+    {
+        return Type::BUILTIN_TYPE_INT === $type->getBuiltinType();
+    }
+}

PropertyDescriber/ObjectPropertyDescriber.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\PropertyDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareInterface;
+use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareTrait;
+use Nelmio\ApiDocBundle\Model\Model;
+use Symfony\Component\PropertyInfo\Type;
+
+class ObjectPropertyDescriber implements PropertyDescriberInterface, ModelRegistryAwareInterface
+{
+    use ModelRegistryAwareTrait;
+
+    public function describe(Type $type, Schema $property, array $groups = null)
+    {
+        $type = new Type($type->getBuiltinType(), false, $type->getClassName(), $type->isCollection(), $type->getCollectionKeyType(), $type->getCollectionValueType()); // ignore nullable field
+
+        $property->setRef(
+            $this->modelRegistry->register(new Model($type, $groups))
+        );
+    }
+
+    public function supports(Type $type): bool
+    {
+        return Type::BUILTIN_TYPE_OBJECT === $type->getBuiltinType();
+    }
+}

PropertyDescriber/PropertyDescriberInterface.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\PropertyDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use Symfony\Component\PropertyInfo\Type;
+
+interface PropertyDescriberInterface
+{
+    public function describe(Type $type, Schema $property, array $groups = null);
+
+    public function supports(Type $type): bool;
+}

PropertyDescriber/StringPropertyDescriber.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\PropertyDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use Symfony\Component\PropertyInfo\Type;
+
+class StringPropertyDescriber implements PropertyDescriberInterface
+{
+    public function describe(Type $type, Schema $property, array $groups = null)
+    {
+        $property->setType('string');
+    }
+
+    public function supports(Type $type): bool
+    {
+        return Type::BUILTIN_TYPE_STRING === $type->getBuiltinType();
+    }
+}

Resources/config/services.xml

@@ -41,6 +41,7 @@
         <service id="nelmio_api_doc.model_describers.object" class="Nelmio\ApiDocBundle\ModelDescriber\ObjectModelDescriber" public="false">
             <argument type="service" id="property_info" />
             <argument type="service" id="annotation_reader" />
+            <argument type="tagged" tag="nelmio_api_doc.object_model.property_describer" />
 
             <tag name="nelmio_api_doc.model_describer" />
         </service>
@@ -49,6 +50,37 @@
             <tag name="nelmio_api_doc.model_describer" priority="-1000" />
         </service>
 
+        <!-- Property Describers -->
+        <service id="nelmio_api_doc.object_model.property_describers.array" class="Nelmio\ApiDocBundle\PropertyDescriber\ArrayPropertyDescriber" public="false">
+            <argument type="tagged" tag="nelmio_api_doc.object_model.property_describer" />
+
+            <tag name="nelmio_api_doc.object_model.property_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.object_model.property_describers.boolean" class="Nelmio\ApiDocBundle\PropertyDescriber\BooleanPropertyDescriber" public="false">
+            <tag name="nelmio_api_doc.object_model.property_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.object_model.property_describers.float" class="Nelmio\ApiDocBundle\PropertyDescriber\FloatPropertyDescriber" public="false">
+            <tag name="nelmio_api_doc.object_model.property_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.object_model.property_describers.integer" class="Nelmio\ApiDocBundle\PropertyDescriber\IntegerPropertyDescriber" public="false">
+            <tag name="nelmio_api_doc.object_model.property_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.object_model.property_describers.string" class="Nelmio\ApiDocBundle\PropertyDescriber\StringPropertyDescriber" public="false">
+            <tag name="nelmio_api_doc.object_model.property_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.object_model.property_describers.date_time" class="Nelmio\ApiDocBundle\PropertyDescriber\DateTimePropertyDescriber" public="false">
+            <tag name="nelmio_api_doc.object_model.property_describer" />
+        </service>
+
+        <service id="nelmio_api_doc.object_model.property_describers.object" class="Nelmio\ApiDocBundle\PropertyDescriber\ObjectPropertyDescriber" public="false">
+            <tag name="nelmio_api_doc.object_model.property_describer" priority="-1000" />
+        </service>
+
         <!-- Form Type Extensions -->
 
         <service id="nelmio_api_doc.form.documentation_extension" class="Nelmio\ApiDocBundle\Form\Extension\DocumentationExtension">