Documentation

app/AppKernel.php

@@ -31,6 +31,8 @@ class AppKernel extends Kernel
             $bundles[] = new Symfony\Bundle\WebProfilerBundle\WebProfilerBundle();
             $bundles[] = new Sensio\Bundle\DistributionBundle\SensioDistributionBundle();
             $bundles[] = new Sensio\Bundle\GeneratorBundle\SensioGeneratorBundle();
+
+            // app (ne pas oublier)
             $bundles[] = new Nelmio\ApiDocBundle\NelmioApiDocBundle();
         }
 

src/AppBundle/Controller/Api/CategoryController.php

@@ -13,6 +13,17 @@ use AppBundle\Form\CategoryType;
 /**
  * class CategoryController.
  *
+ * Les controleurs de ce type (chargés un à un via `routing.yml`)
+ * permettent de créer des accès type API.
+ *
+ * La nomenclature des méthodes permettent de définir
+ * le type de requête HTTP permis et la route associée.
+ *
+ * Il est possible de modifier le chemin (je l'ai fais pour l'exemple).
+ *
+ * Tout ce qui est @ApiDoc permet de générer les données pour la sandox
+ * qui fait aussi office de documentation pour l'API.
+ *
  * @author Simon Vieille <simon@deblan.fr>
  */
 class CategoryController extends FOSRestController

src/AppBundle/Controller/CategoryController.php

@@ -19,6 +19,11 @@ class CategoryController extends Controller
     /**
      * Categories page.
      *
+     * Cette action permet d'afficher le formulaire pour
+     * ajouter une catégorie. Le javascript inscrit dans le template
+     * associé va faire appel à l'API pour afficher les catégories
+     * existantes et permettre d'en ajouter.
+     *
      * @Template()
      * @Route("/", name="example")
      *

src/AppBundle/Entity/Category.php

@@ -7,6 +7,15 @@ use Doctrine\ORM\Mapping as ORM;
 /**
  * Category.
  *
+ * Tous les objets retournés dans l'API sont transformés
+ * de manière à pouvoir être retournés au format JSON ou XML.
+ * Le comportement par défaut est de récupérer l'ensemble des attributs
+ * et de les retourner tels quels. Je prend le parti de choisir
+ * les données à afficher via les annotations JMS et les méthodes
+ * que je préfix par `getRest`. Ça permet donc de filtrer
+ * ce que l'on veut voir apparître dans l'API et ce qui ne doit pas y
+ * figurer.
+ *
  * @ORM\Table(name="category")
  * @ORM\Entity(repositoryClass="AppBundle\Repository\CategoryRepository")
  * @JMS\Serializer\Annotation\ExclusionPolicy("all")

src/AppBundle/Form/CategoryType.php

@@ -21,7 +21,11 @@ class CategoryType extends AbstractType
             TextType::class,
             [
                 'label' => 'Nom',
-                'required' => false, // html5 validation disable for the example
+                // Je vire le required HTML pour permettre de valider
+                // le formulaire avec une donnée vide et non valide
+                // Tu pourras voir de quelle manière les erreurs
+                // sont remontées
+                'required' => false,
                 'constraints' => [
                     new NotBlank(),
                 ],
@@ -36,6 +40,7 @@ class CategoryType extends AbstractType
     {
         $resolver->setDefaults([
             'data_class' => Category::class,
+            // Ces 2 configurations sont importantes
             'csrf_protection' => false,
             'allow_extra_fields' => true,
         ]);
@@ -46,6 +51,7 @@ class CategoryType extends AbstractType
      */
     public function getBlockPrefix()
     {
+        // Très important également
         return '';
     }
 }

src/AppBundle/Resources/views/Category/index.html.twig

@@ -21,10 +21,14 @@
 <script src="{{ asset('bundles/fosjsrouting/js/fos_js_routes.js') }}"></script>
 
 <script>
+// J'utilise jQuery par flemme
 (function(w, $) {
     var listCategories = function() {
         $.ajax({
-            url: Routing.generate('get_categories'), // Si tes scripts sont dans un fichiers JS
+            // Si tes scripts sont dans un fichiers JS
+            // tu peux accéder aux routes (et les générer)
+            // via cette méthode (voir le README)
+            url: Routing.generate('get_categories'),
         }).done(function(collection) {
             var $list = $('#list').html('');
 
@@ -47,6 +51,11 @@
             $('#response').text(JSON.stringify(response));
             listCategories();
         }).fail(function(response) {
+            // En cas d'erreur, l'API est faite de telle sorte
+            // que les données mal saisies soient remontées avec le message
+            // d'erreur associé.
+            // Avec un peu de code, tu peux automatiser l'affichage des erreurs
+            // puisque les erreurs sont associés à leur champ respectif.
             $('#response').text(JSON.stringify(response.responseJSON, null, 4));
             listCategories();
         });