fix doc for api

docs/source/development/api.rst

@@ -6,7 +6,7 @@
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".
 
-.. _api
+.. _api:
 
 API
 ###
@@ -26,7 +26,9 @@ You can also:
 * hook into the controller to customize some steps;
 * add more route and steps
 
-.. read-also::
+.. note::
+
+    Useful links:
 
     * `How to use annotation to configure serialization <https://symfony.com/doc/current/serializer.html>`_
     * `How to create your custom normalizer <https://symfony.com/doc/current/serializer/custom_normalizer.html>`_
@@ -87,7 +89,7 @@ Create your model on the usual way:
 Configure api
 *************
 
-Configure the api using Yaml (see the full configuration below):
+Configure the api using Yaml (see the full configuration: :ref:`api_full_configuration`):
 
 .. code-block:: yaml
 
@@ -359,7 +361,46 @@ Then, create the corresponding action into your controller:
        }
    }
 
-.. api_full_config:
+Serialization for collection
+============================
+
+A specific model has been defined for returning collection:
+
+.. code-block:: json
+
+   {
+       "count": 49,
+       "results": [
+       ],
+       "pagination": {
+           "more": true,
+           "next": "/api/1.0/search.json&q=xxxx......&page=2",
+           "previous": null,
+           "first": 0,
+           "items_per_page": 1
+       }
+   }
+
+
+This can be achieved quickly by assembling results into a :code:`Chill\MainBundle\Serializer\Model\Collection`. The pagination information is given by using :code:`Paginator` (see :ref:`Pagination <pagination-ref>`).
+
+.. code-block:: php
+
+   use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+   use Chill\MainBundle\Pagination\PaginatorInterface;
+
+   class MyController extends AbstractController
+   {
+
+       protected function serializeCollection(PaginatorInterface $paginator, $entities): Response
+       {
+           $model = new Collection($entities, $paginator);
+
+           return $this->json($model, Response::HTTP_OK, [], $context);
+       }
+   }
+
+.. _api_full_configuration:
 
 Full configuration example
 ==========================

docs/source/development/index.rst

@@ -16,6 +16,7 @@ As Chill rely on the `symfony <http://symfony.com>`_ framework, reading the fram
 
     Instructions to create a new bundle <create-a-new-bundle.rst>
     CRUD (Create - Update - Delete) for one entity <crud.rst>
+    Helpers for building a REST API <api.rst>
     Routing <routing.rst>
     Menus <menus.rst>
     Forms <forms.rst>

docs/source/development/pagination.rst

@@ -7,6 +7,8 @@
    Free Documentation License".
 
 
+.. _pagination-ref:
+
 Pagination
 ##########
 
@@ -15,7 +17,7 @@ The Bundle :code:`Chill\MainBundle` provides a **Pagination** api which allow yo
 A simple example
 ****************
 
-In the controller, get the :class:`Chill\Main\Pagination\PaginatorFactory` from the `Container` and use this :code:`PaginatorFactory` to create a :code:`Paginator` instance.
+In the controller, get the :code:`Chill\Main\Pagination\PaginatorFactory` from the `Container` and use this :code:`PaginatorFactory` to create a :code:`Paginator` instance.
 
 
 .. literalinclude:: pagination/example.php