set up DI and add type support

DependencyInjection/NelmioApiDocExtension.php

@@ -103,6 +103,7 @@ final class NelmioApiDocExtension extends Extension implements PrependExtensionI
                     new Reference('jms_serializer.metadata_factory'),
                     new Reference('jms_serializer.naming_strategy'),
                     new Reference('nelmio_api_doc.model_describers.swagger_property_annotation_reader'),
+                    new Reference('nelmio_api_doc.model_describers.phpdoc_property_annotation_reader'),
                 ])
                 ->addTag('nelmio_api_doc.model_describer', ['priority' => 50]);
         }

ModelDescriber/JMSModelDescriber.php

@@ -35,14 +35,18 @@ class JMSModelDescriber implements ModelDescriberInterface, ModelRegistryAwareIn
 
     private $swaggerPropertyAnnotationReader;
 
+    private $phpdocPropertyAnnotationsReader;
+
     public function __construct(
         MetadataFactoryInterface $factory,
         PropertyNamingStrategyInterface $namingStrategy,
-        SwaggerPropertyAnnotationReader $swaggerPropertyAnnotationReader
+        SwaggerPropertyAnnotationReader $swaggerPropertyAnnotationReader,
+        PhpdocPropertyAnnotationReader $phpdocPropertyAnnotationReader
     ) {
         $this->factory = $factory;
         $this->namingStrategy = $namingStrategy;
         $this->swaggerPropertyAnnotationReader = $swaggerPropertyAnnotationReader;
+        $this->phpdocPropertyAnnotationsReader = $phpdocPropertyAnnotationReader;
     }
 
     /**
@@ -103,8 +107,7 @@ class JMSModelDescriber implements ModelDescriberInterface, ModelRegistryAwareIn
 
             // read property options from Swagger Property annotation if it exists
             if (null !== $item->reflection) {
-                $phpdocReader = new PhpdocAnnotationReader();
-                $phpdocReader->updateWithPhpdoc($item->reflection, $realProp);
+                $this->phpdocPropertyAnnotationsReader->updateWithPhpdoc($item->reflection, $realProp);
                 $this->swaggerPropertyAnnotationReader->updateWithSwaggerPropertyAnnotation($item->reflection, $realProp);
             }
         }

ModelDescriber/PhpdocPropertyAnnotationReader.php

@@ -18,9 +18,11 @@ use phpDocumentor\Reflection\DocBlockFactory;
 use phpDocumentor\Reflection\DocBlockFactoryInterface;
 
 /**
+ * Extract information about properties of a model from the DocBlock comment.
+ *
  * @internal
  */
-class PhpdocAnnotationReader
+class PhpdocPropertyAnnotationReader
 {
     private $docBlockFactory;
 
@@ -33,6 +35,8 @@ class PhpdocAnnotationReader
     }
 
     /**
+     * Update the Swagger information with information from the DocBlock comment.
+     *
      * @param \ReflectionProperty $reflectionProperty
      * @param Items|Schema        $property
      */
@@ -40,22 +44,33 @@ class PhpdocAnnotationReader
     {
         try {
             $docBlock = $this->docBlockFactory->create($reflectionProperty);
-            if (!$title = $docBlock->getSummary()) {
-                /** @var Var_ $var */
-                foreach ($docBlock->getTagsByName('var') as $var) {
-                    if (null === $description = $var->getDescription()) continue;
-                    $title = $description->render();
-                    if ($title) break;
-                }
-            }
-            if ($property->getTitle() === null && $title) {
-                $property->setTitle($title);
-            }
-            if ($property->getDescription() === null && $docBlock->getDescription()) {
-                $property->setDescription($docBlock->getDescription()->render());
-            }
         } catch (\Exception $e) {
             // ignore
+            return;
+        }
+
+        if (!$title = $docBlock->getSummary()) {
+            /** @var Var_ $var */
+            foreach ($docBlock->getTagsByName('var') as $var) {
+                if (null === $description = $var->getDescription()) continue;
+                $title = $description->render();
+                if ($title) break;
+            }
+        }
+        if ($property->getTitle() === null && $title) {
+            $property->setTitle($title);
+        }
+        if ($property->getDescription() === null && $docBlock->getDescription()) {
+            $property->setDescription($docBlock->getDescription()->render());
+        }
+        if ($property->getType() === null) {
+            /** @var Var_ $var */
+            foreach ($docBlock->getTagsByName('var') as $var) {
+                if ($var->getType()) {
+                    $property->setType($var->getType());
+                    break;
+                }
+            }
         }
     }
 }

README.md

@@ -151,7 +151,7 @@ serialization groups when using the Symfony serializer.
 ### If you're using the JMS Serializer
 
 The metadata of the JMS serializer are used by default to describe your
-models.
+models. Additional information is extracted from the PHP doc block comment.
 
 In case you prefer using the [Symfony PropertyInfo component](https://symfony.com/doc/current/components/property_info.html) (you
 won't be able to use JMS serialization groups), you can disable JMS serializer

Resources/config/services.xml

@@ -54,6 +54,12 @@
             <argument type="service" id="annotation_reader" />
         </service>
 
+        <service
+                id="nelmio_api_doc.model_describers.phpdoc_property_annotation_reader"
+                class="Nelmio\ApiDocBundle\ModelDescriber\PhpdocPropertyAnnotationReader"
+                public="false"
+        />
+
         <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="nelmio_api_doc.model_describers.swagger_property_annotation_reader" />