Handle Symfony serializer datetime_format context for date formatting

Author: Matthew-Kilpatrick

src/ModelDescriber/Annotations/AnnotationsReader.php

@@ -23,7 +23,7 @@ class AnnotationsReader
 {
     private PropertyPhpDocReader $phpDocReader;
     private OpenApiAnnotationsReader $openApiAnnotationsReader;
-    private SymfonyConstraintAnnotationReader $symfonyConstraintAnnotationReader;
+    private SymfonyAnnotationReader $symfonyAnnotationReader;
     private ReflectionReader $reflectionReader;
 
     /**
@@ -36,14 +36,14 @@ public function __construct(
     ) {
         $this->phpDocReader = new PropertyPhpDocReader();
         $this->openApiAnnotationsReader = new OpenApiAnnotationsReader($modelRegistry, $mediaTypes);
-        $this->symfonyConstraintAnnotationReader = new SymfonyConstraintAnnotationReader($useValidationGroups);
+        $this->symfonyAnnotationReader = new SymfonyAnnotationReader($useValidationGroups);
         $this->reflectionReader = new ReflectionReader();
     }
 
     public function updateDefinition(\ReflectionClass $reflectionClass, OA\Schema $schema): bool
     {
         $this->openApiAnnotationsReader->updateSchema($reflectionClass, $schema);
-        $this->symfonyConstraintAnnotationReader->setSchema($schema);
+        $this->symfonyAnnotationReader->setSchema($schema);
         $this->reflectionReader->setSchema($schema);
 
         return $this->shouldDescribeModelProperties($schema);
@@ -66,7 +66,7 @@ public function updateProperty($reflection, OA\Property $property, ?array $seria
         $this->openApiAnnotationsReader->updateProperty($reflection, $property, $serializationGroups);
         $this->phpDocReader->updateProperty($reflection, $property);
         $this->reflectionReader->updateProperty($reflection, $property);
-        $this->symfonyConstraintAnnotationReader->updateProperty($reflection, $property, $serializationGroups);
+        $this->symfonyAnnotationReader->updateProperty($reflection, $property, $serializationGroups);
     }
 
     /**

src/ModelDescriber/Annotations/ReflectionReader.php

@@ -18,7 +18,7 @@
 /**
  * Read default values of a property from the function or property signature.
  *
- * This needs to be called before the {@see SymfonyConstraintAnnotationReader},
+ * This needs to be called before the {@see SymfonyAnnotationReader},
  * otherwise required properties might be considered wrongly.
  *
  * @internal

src/ModelDescriber/Annotations/SymfonyConstraintAnnotationReader.php renamed to src/ModelDescriber/Annotations/SymfonyAnnotationReader.php

@@ -22,7 +22,7 @@
 /**
  * @internal
  */
-class SymfonyConstraintAnnotationReader
+class SymfonyAnnotationReader
 {
     use SetsContextTrait;
 
@@ -39,27 +39,37 @@ public function __construct(bool $useValidationGroups = false)
     }
 
     /**
-     * Update the given property and schema with defined Symfony constraints.
+     * Update the given property and schema with defined Symfony attributes.
      *
      * @param \ReflectionProperty|\ReflectionMethod $reflection
      * @param string[]|null                         $validationGroups
      */
     public function updateProperty($reflection, OA\Property $property, ?array $validationGroups = null): void
     {
-        foreach ($this->getAttributes($property->_context, $reflection, $validationGroups) as $outerAttribute) {
+        // Handle constraints
+        foreach ($this->getConstraintAttributes($property->_context, $reflection, $validationGroups) as $outerAttribute) {
             $innerAttributes = $outerAttribute instanceof Assert\Compound || $outerAttribute instanceof Assert\Sequentially
                 ? $outerAttribute->constraints
                 : [$outerAttribute];
 
-            $this->processPropertyAttributes($reflection, $property, $innerAttributes);
+            $this->processConstraintPropertyAttributes($reflection, $property, $innerAttributes);
+        }
+
+        // Handle context
+        $context = $reflection->getAttributes(\Symfony\Component\Serializer\Attribute\Context::class);
+        if (1 === \count($context)) {
+            $contextArgs = $context[0]->getArguments()[0];
+            if ('Y-m-d' === ($contextArgs['datetime_format'] ?? null)) {
+                $property->format = 'date';
+            }
         }
     }
 
     /**
      * @param \ReflectionProperty|\ReflectionMethod $reflection
      * @param Constraint[]                          $attributes
      */
-    private function processPropertyAttributes($reflection, OA\Property $property, array $attributes): void
+    private function processConstraintPropertyAttributes($reflection, OA\Property $property, array $attributes): void
     {
         foreach ($attributes as $attribute) {
             if ($attribute instanceof Assert\NotBlank || $attribute instanceof Assert\NotNull) {
@@ -179,7 +189,7 @@ private function applyEnumFromChoiceConstraint(OA\Schema $property, Assert\Choic
      *
      * @return iterable<Constraint>
      */
-    private function getAttributes(Context $parentContext, $reflection, ?array $validationGroups): iterable
+    private function getConstraintAttributes(Context $parentContext, $reflection, ?array $validationGroups): iterable
     {
         // To correctly load OA attributes
         $this->setContextFromReflection($parentContext, $reflection);

src/PropertyDescriber/DateTimePropertyDescriber.php

@@ -12,6 +12,7 @@
 namespace Nelmio\ApiDocBundle\PropertyDescriber;
 
 use OpenApi\Annotations as OA;
+use OpenApi\Generator;
 use Symfony\Component\PropertyInfo\Type;
 
 final class DateTimePropertyDescriber implements PropertyDescriberInterface
@@ -22,7 +23,9 @@ final class DateTimePropertyDescriber implements PropertyDescriberInterface
     public function describe(array $types, OA\Schema $property, array $context = []): void
     {
         $property->type = 'string';
-        $property->format = 'date-time';
+        if (Generator::UNDEFINED === $property->format) {
+            $property->format = 'date-time';
+        }
     }
 
     public function supports(array $types, array $context = []): bool

tests/Functional/Entity/SymfonyContext.php

@@ -0,0 +1,26 @@
+<?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\Tests\Functional\Entity;
+
+use Symfony\Component\Serializer\Attribute\Context;
+
+class SymfonyContext
+{
+    /**
+     * @var \DateTime
+     */
+    #[Context(['datetime_format' => 'Y-m-d'])]
+    public $date;
+
+    #[Context(['datetime_format' => 'Y-m-d'])]
+    public ?\DateTime $nullableDate = null;
+}

tests/Functional/FunctionalTest.php

@@ -780,6 +780,29 @@ public function testPrivateProtectedExposure(): void
         $this->assertNotHasProperty('protected', $model);
     }
 
+    public function testContextSupport(): void
+    {
+        self::assertEquals(
+            [
+                'schema' => 'SymfonyContext',
+                'type' => 'object',
+                'required' => ['date'],
+                'properties' => [
+                    'date' => [
+                        'type' => 'string',
+                        'format' => 'date',
+                    ],
+                    'nullableDate' => [
+                        'type' => 'string',
+                        'format' => 'date',
+                        'nullable' => true,
+                    ],
+                ],
+            ],
+            json_decode($this->getModel('SymfonyContext')->toJson(), true)
+        );
+    }
+
     public function testModelsWithDiscriminatorMapAreLoadedWithOpenApiPolymorphism(): void
     {
         $model = $this->getModel('SymfonyDiscriminator');

tests/Functional/TestKernel.php

@@ -22,6 +22,7 @@
 use Nelmio\ApiDocBundle\Tests\Functional\Entity\NestedGroup\JMSPicture;
 use Nelmio\ApiDocBundle\Tests\Functional\Entity\PrivateProtectedExposure;
 use Nelmio\ApiDocBundle\Tests\Functional\Entity\SymfonyConstraintsWithValidationGroups;
+use Nelmio\ApiDocBundle\Tests\Functional\Entity\SymfonyContext;
 use Nelmio\ApiDocBundle\Tests\Functional\ModelDescriber\NameConverter;
 use Nelmio\ApiDocBundle\Tests\Functional\ModelDescriber\VirtualTypeClassDoesNotExistsHandlerDefinedDescriber;
 use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
@@ -177,6 +178,11 @@ protected function configureContainer(ContainerBuilder $c, LoaderInterface $load
                 'type' => BazingaUser::class,
                 'groups' => ['foo'],
             ],
+            [
+                'alias' => 'SymfonyContext',
+                'type' => SymfonyContext::class,
+                'groups' => null,
+            ],
             [
                 'alias' => 'SymfonyConstraintsTestGroup',
                 'type' => SymfonyConstraintsWithValidationGroups::class,