add a discrimnator type on onbjects

docs/source/development/api.rst

@@ -49,7 +49,12 @@ Ensure that those lines are present in your file `app/config/routing.yml`:
 Create your model
 *****************
 
-Create your model on the usual way:
+Create your model on the usual way.
+
+If you do not use a `custom normalizer <https://symfony.com/doc/current/serializer/custom_normalizer.html>`_, you must add `annotations to create serialization groups <https://symfony.com/doc/current/components/serializer.html#attributes-groups>`_. Those groups are, by defaults:
+
+* :code:`read` for GET requests;
+* :code:`write` for POST, PUT and PATCH requests
 
 .. code-block:: php
 
@@ -57,6 +62,7 @@ Create your model on the usual way:
 
    use Chill\PersonBundle\Entity\AccompanyingPeriod\OriginRepository;
    use Doctrine\ORM\Mapping as ORM;
+   use Symfony\Component\Serializer\Annotation\Groups;
 
    /**
     * @ORM\Entity(repositoryClass=OriginRepository::class)
@@ -68,16 +74,19 @@ Create your model on the usual way:
         * @ORM\Id
         * @ORM\GeneratedValue
         * @ORM\Column(type="integer")
+        * @Groups({"read"})
         */
        private $id;
 
        /**
         * @ORM\Column(type="json")
+        * @Groups({"read", "write"})
         */
        private $label;
 
        /**
         * @ORM\Column(type="date_immutable", nullable=true)
+        * @Groups({"read", "write"})
         */
        private $noActiveAfter;
 
@@ -215,6 +224,48 @@ You can also define a role for each method. In this case, this role is used for
                            GET: MY_ROLE_SEE
                            HEAD: MY ROLE_SEE
 
+Edit an entity: PUT and PATCH requests
+=======================================
+
+By default, PUT and PATCH requests are not enabled. You may enable it into the configuration:
+
+
+.. code-block:: yaml
+
+   # config/packages/chill_main.yaml
+   chill_main:
+       apis:
+           accompanying_period_origin:
+               base_path: '/api/1.0/person/bla/bla'
+               class: 'Chill\PersonBundle\Entity\Blah'
+               name: bla
+               actions:
+                   _entity:
+                       methods:
+                           GET: true
+                           HEAD: true
+                           PUT: true
+                           PATCH: true
+                       roles:
+                           GET: MY_ROLE_SEE
+                           HEAD: MY ROLE_SEE
+                           HEAD: MY ROLE_UPDATE
+                           HEAD: MY ROLE_UPDATE
+
+.. note::
+
+   PUT and PATCH requests are handled on a similar way. You may use both without difference, although updating a whole object should use a PUT request, and updating part of the object should use a PATCH request.
+
+Those two requests allow natively to update all attributes which are present in :code:`write` group, and relation which are connected in ManyToOne relation (the entity under :code:`class` config must be associated with one entity).
+
+The api will be able to load the associated entity with a simple given :code:`id` and :code:`type`, if
+
+* if the class is an entity, managed by Doctrine;
+* if a discriminator map is present;
+* if the given data has two keys: the "discriminator map" (:code:`type`) and the id. Example: :code:`{ "type": "person", "id": 2205 }`;
+* if the :code:`setter` is type-hinted.
+
+
 Customize the controller
 ========================