feat(validation): add section on collecting denormalization errors (#1643)

Author: natacha-h

core/configuration.md

@@ -64,7 +64,7 @@ api_platform:
 
     # Enable the docs.
     enable_docs: true
-    
+
     # Enable the data collector and the WebProfilerBundle integration.
     enable_profiler: true
 
@@ -157,7 +157,7 @@ api_platform:
     swagger:
         # The active versions of OpenAPI to be exported or used in the swagger_ui. The first value is the default.
         versions: [2, 3]
-                
+
         # The swagger API keys.
         api_keys: []
             # The name of the header or query parameter containing the API key.
@@ -192,7 +192,7 @@ api_platform:
             url:
 
         swagger_ui_extra_configuration:
-            # Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing). 
+            # Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing).
             docExpansion: list
             # If set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown.
             filter: false
@@ -375,5 +375,8 @@ api_platform:
         # The URL generation strategy to use for IRIs
         url_generation_strategy: !php/const ApiPlatform\Api\UrlGeneratorInterface::ABS_PATH
 
+        # To enable collecting denormalization errors
+        collectDenormalizationErrors: false
+
         # ...
 ```

core/validation.md

@@ -26,7 +26,7 @@ use Symfony\Component\Validator\Constraints as Assert; // Symfony's built-in con
  * A product.
  *
  */
-#[ORM\Entity] 
+#[ORM\Entity]
 #[ApiResource]
 class Product
 {
@@ -42,7 +42,7 @@ class Product
      *
      * @MinimalProperties
      */
-    #[ORM\Column(type: 'json')] 
+    #[ORM\Column(type: 'json')]
     public $properties;
 
     // Getters and setters...
@@ -130,10 +130,10 @@ use Symfony\Component\Validator\Constraints as Assert;
 #[ApiResource(validationContext: ['groups' => ['a', 'b']])]
 class Book
 {
-    #[Assert\NotBlank(groups: ['a'])]  
+    #[Assert\NotBlank(groups: ['a'])]
     public string $name;
 
-    #[Assert\NotNull(groups: ['b'])] 
+    #[Assert\NotNull(groups: ['b'])]
     public string $author;
 
     // ...
@@ -175,15 +175,15 @@ use Symfony\Component\Validator\Constraints as Assert;
 #[Post(validationContext: ['groups' => ['Default', 'postValidation']])]
 class Book
 {
-    #[Assert\Uuid] 
+    #[Assert\Uuid]
     private $id;
 
-    #[Assert\NotBlank(groups: ['postValidation'])] 
+    #[Assert\NotBlank(groups: ['postValidation'])]
     public $name;
 
     #[Assert\NotNull]
     #[Assert\Length(min: 2, max: 50, groups: ['postValidation'])]
-    #[Assert\Length(min: 2, max: 70, groups: ['putValidation'])] 
+    #[Assert\Length(min: 2, max: 70, groups: ['putValidation'])]
     public $author;
 
     // ...
@@ -230,10 +230,10 @@ class Book
         return ['a'];
     }
 
-    #[Assert\NotBlank(groups: ['a'])] 
+    #[Assert\NotBlank(groups: ['a'])]
     public $name;
 
-    #[Assert\NotNull(groups: ['b'])] 
+    #[Assert\NotNull(groups: ['b'])]
     public $author;
 
     // ...
@@ -291,10 +291,10 @@ use Symfony\Component\Validator\Constraints as Assert;
 #[ApiResource(validationContext: ['groups' => [AdminGroupsGenerator::class]])
 class Book
 {
-    #[Assert\NotBlank(groups: ['a'])] 
+    #[Assert\NotBlank(groups: ['a'])]
     public $name;
 
-    #[Assert\NotNull(groups: ['b'])] 
+    #[Assert\NotNull(groups: ['b'])]
     public $author;
 
     // ...
@@ -354,7 +354,7 @@ class Greeting
 
     /**
      * @var A nice person
-     * 
+     *
      * I want this "second" validation to be executed after the "first" one even though I wrote them in this order.
      * @One(groups={"second"})
      * @Two(groups={"first"})
@@ -523,7 +523,7 @@ Constraints
 [`Isbn`](https://symfony.com/doc/current/reference/constraints/Isbn.html)             | `https://schema.org/isbn`          |
 [`Issn`](https://symfony.com/doc/current/reference/constraints/Issn.html)             | `https://schema.org/issn`          |
 
-## Specification property restrictions
+## Specification Property Restrictions
 
 API Platform generates specification property restrictions based on Symfony’s built-in validator.
 
@@ -555,7 +555,7 @@ final class CustomPropertySchemaRestriction implements PropertySchemaRestriction
         return $constraint instanceof CustomConstraint;
     }
 
-    public function create(Constraint $constraint, ApiProperty $propertyMetadata): array 
+    public function create(Constraint $constraint, ApiProperty $propertyMetadata): array
     {
       // your logic to create property schema restriction based on constraint
       return $restriction;
@@ -573,3 +573,52 @@ services:
     'App\PropertySchemaRestriction\CustomPropertySchemaRestriction': ~
         # Uncomment only if autoconfiguration is disabled
         #tags: [ 'api_platform.metadata.property_schema_restriction' ]
+```
+
+## Collecting Denormalization Errors
+
+When submitting data you can collect denormalization errors using the [COLLECT_DENORMALIZATION_ERRORS option](https://symfony.com/doc/current/components/serializer.html#collecting-type-errors-while-denormalizing).
+
+It can be done directly in the `#[ApiResource]` attribute (or in the operations):
+
+```php
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+
+#[ApiResource(
+    collectDenormalizationErrors: true
+)]
+class Book
+{
+    public ?bool $boolean;
+    public ?string $property1;
+}
+```
+
+If the submitted data has denormalization errors, the HTTP status code will be set to `422 Unprocessable Content` and the response body will contain the list of errors:
+
+```json
+{
+    "@context": "/api/contexts/ConstraintViolationList",
+    "@type": "ConstraintViolationList",
+    "hydra:title": "An error occurred",
+    "hydra:description": "boolean: This value should be of type bool.\nproperty1: This value should be of type string.",
+    "violations": [
+        {
+            "propertyPath": "boolean",
+            "message": "This value should be of type bool.",
+            "code": "0"
+        },
+        {
+            "propertyPath": "property1",
+            "message": "This value should be of type string.",
+            "code": "0"
+        }
+    ]
+}
+```
+
+You can also enable collecting of denormalization errors globally in the [Global Resources Defaults](https://api-platform.com/docs/core/configuration/#global-resources-defaults).