From 3fa948aee8acc001a70214cfd5443910e8d7fe85 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Tue, 19 Dec 2017 08:41:24 +0100 Subject: [PATCH] set up DI and add type support --- DependencyInjection/NelmioApiDocExtension.php | 1 + ModelDescriber/JMSModelDescriber.php | 9 ++-- ...php => PhpdocPropertyAnnotationReader.php} | 45 ++++++++++++------- README.md | 2 +- Resources/config/services.xml | 6 +++ 5 files changed, 44 insertions(+), 19 deletions(-) rename ModelDescriber/{PhpdocAnnotationReader.php => PhpdocPropertyAnnotationReader.php} (52%) diff --git a/DependencyInjection/NelmioApiDocExtension.php b/DependencyInjection/NelmioApiDocExtension.php index 6f05139..19cba17 100644 --- a/DependencyInjection/NelmioApiDocExtension.php +++ b/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]); } diff --git a/ModelDescriber/JMSModelDescriber.php b/ModelDescriber/JMSModelDescriber.php index a4ae751..47b0bb9 100644 --- a/ModelDescriber/JMSModelDescriber.php +++ b/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); } } diff --git a/ModelDescriber/PhpdocAnnotationReader.php b/ModelDescriber/PhpdocPropertyAnnotationReader.php similarity index 52% rename from ModelDescriber/PhpdocAnnotationReader.php rename to ModelDescriber/PhpdocPropertyAnnotationReader.php index 83fb1f1..9c5bebc 100644 --- a/ModelDescriber/PhpdocAnnotationReader.php +++ b/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; + } + } } } } diff --git a/README.md b/README.md index 4030c6f..e6650b4 100644 --- a/README.md +++ b/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 diff --git a/Resources/config/services.xml b/Resources/config/services.xml index 00443e4..401b78d 100644 --- a/Resources/config/services.xml +++ b/Resources/config/services.xml @@ -54,6 +54,12 @@ + +