Document input/output resource attribute

Author: soyuka

core/dto.md

@@ -350,3 +350,73 @@ use Swagger\Annotations as SWG;
      */
     public function __invoke()
 ```
+
+### Specify an input and/or output class
+
+For a given resource class, you may want to have a different representation of this class as input (write) or output (read).
+To do so, a resource can take an input and/or an output class:
+
+```php
+<?php
+// api/src/Entity/Data.php
+
+namespace App\Entity;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use App\Dto\Input;
+use App\Dto\Output;
+
+/**
+ * @ApiResource(attributes={
+ *    "input_class"=Input::class,
+ *    "output_class"Output::class
+ * })
+ */
+final class Data
+{
+}
+```
+
+The `input_class` attribute will be used in the denormalization phase, when transforming the user data to a resource instance.
+The `output_class` attribute will be used in the normalization phase, this class represents how the `Data` resource will be given in the `Response`.
+
+To create a `Data`, we `POST` an `Input` and get back an `Output` in the response.
+For this example to work, one could use the following `DataPersister`:
+
+```php
+<?php
+
+namespace App\DataPersister;
+
+use ApiPlatform\Core\DataPersister\DataPersisterInterface;
+use App\Dto\Input;
+use App\Dto\Output;
+
+class InputDataPersister implements DataPersisterInterface
+{
+    public function supports($data): bool
+    {
+        return $data instanceof Input;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function persist($data)
+    {
+        $output = new Output();
+        $output->name = $data->name;
+        $output->id = 1;
+
+        return $output;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function remove($data)
+    {
+        return null;
+    }
+}
+```