• 50 heures
  • Difficile

Ce cours est visible gratuitement en ligne.

course.header.alt.is_video

course.header.alt.is_certifying

J'ai tout compris !

Mis à jour le 29/07/2019

Documentez votre API

Connectez-vous ou inscrivez-vous gratuitement pour bénéficier de toutes les fonctionnalités de ce cours !

 

La qualité d'une API REST passe par la documentation de celle-ci : en effet, il s'agit de faciliter l'utilisation de son API pour une adoption la plus rapide possible.

Voyons dès maintenant comment mettre en place une documentation très rapidement au sein de son API. Devinez quoi ! Il y a un bundle pour ça ! ;)

Installation du NelmioApiDocBundle

Commençons par installer le bundle, pour ce faire, tapez la commande suivante :

$ composer require nelmio/api-doc-bundle
Installation du NelmioApiDocBundle
Installation du NelmioApiDocBundle

Il faut ensuite déclarer le bundle dans la classe  AppKernel:

<?php

use Symfony\Component\HttpKernel\Kernel;
use Symfony\Component\Config\Loader\LoaderInterface;

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            //…
            new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
        ];

        // …

        return $bundles;
    }
    // …
}

La documentation sera visible sur des pages générées par le bundle. Il faut déclarer les routes du bundle pour y avoir accès. Ouvrez le fichier app/config/routing.yml et ajoutez le code suivant :

# app/config/routing.yml

NelmioApiDocBundle:
    resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
    prefix:   /api/doc

Et enfin, il faut configurer le bundle. Il s'agit de déclarer une configuration par défaut. Je vous invite à ouvrir le fichier app/config/config.yml et y taper le code suivant :

# app/config/config.yml

# …

nelmio_api_doc: ~

 

Tout est bon ! Je vous invite à vérifier que la page de base est disponible en vous rendant sur la page http://127.0.0.1:8001/api/doc, vous devriez voir ce qui suit :

Page par défaut de documentation
Page par défaut de documentation

Mise en place de la documentation avec le NelmioApiDocBundle

Documentation de base

Pour documenter chacune des routes de notre API, il suffit d'ajouter une annotation comme suit :

<?php

namespace AppBundle\Controller;

use Nelmio\ApiDocBundle\Annotation as Doc;

class ArticleController extends FOSRestController
{
    /**
     * …
     *
     * @Doc\ApiDoc(
     *     resource=true,
     *     description="Get the list of all articles."
     * )
     */
    public function listAction(ParamFetcherInterface $paramFetcher)
    {
        //…

Rafraîchissez la page http://127.0.0.1:8001/api/doc et vous pourrez voir que la documentation a été mise à jour !

Page de documentation mise à jour
Page de documentation mise à jour

Comme nous pouvons le voir, les paramètres qu'il est possible de passer sont également indiqués ! Le bundle dispose d'une intégration facilitée avec le FOSRestBundle. Bonne nouvelle ! :D

Ajout d'informations concernant les exigences requises (requirements)

Prenons le point d'entrée en charge de la récupération d'un article : nous pouvons indiquer aux utilisateurs de l'API les exigences pour l'id qu'il faut passer dans l'URL. Voici comment faire dans le code :

<?php

namespace AppBundle\Controller;

// …

class ArticleController extends FOSRestController
{
    /**
     * …
     * 
     * @Doc\ApiDoc(
     *     resource=true,
     *     description="Get one article.",
     *     requirements={
     *         {
     *             "name"="id",
     *             "dataType"="integer",
     *             "requirements"="\d+",
     *             "description"="The article unique identifier."
     *         }
     *     }
     * )
     */
    public function showAction(Article $article)
    {
        // …

En rafraîchissant la page de documentation, l'on peut voir que, pour ce point d'entrée, les indications mises en annotation sont apparues dans la documentation :

Documentation pour la récupération d'un article
Documentation pour la récupération d'un article

Ajout d'une section

Il est possible de créer des sections dans la documentation en indiquant pour chacun des points d'entrée auquel il appartient :

<?php

namespace AppBundle\Controller;

//… 
class ArticleController extends FOSRestController
{
    /**
     * …
     *
     * @Doc\ApiDoc(
     *     section="Articles",
     *     …
     * )
     */
    public function listAction(ParamFetcherInterface $paramFetcher)
    {
        // …
    }
    
    /**
     * …
     * 
     * @Doc\ApiDoc(
     *     section="Articles",
     *     …
     * )
     */
    public function showAction(Article $article)
    {
        // …

 La présentation devient un peu plus claire, en particulier lorsque le nombre de points d'entrée est conséquent :

Ajout d'une section
Ajout d'une section "Articles"

Indication des codes status HTTP que le point d'entrée peut retourner

Pour lister tous les codes status possibles, il suffit de les lister comme suit en annotation :

<?php

namespace AppBundle\Controller;

// …

class ArticleController extends FOSRestController
{
    /**
     * …
     *
     * @Doc\ApiDoc(
     *     …
     *     statusCodes={
     *         201="Returned when created",
     *         400="Returned when a violation is raised by validation"
     *     }
     * )
     */
    public function createAction(Article $article, ConstraintViolationList $violations)
    {

 Voici le résultat :

Liste des codes status que le point d'entrée peut retourner
Liste des codes status que le point d'entrée peut retourner en réponse

La Sandbox 

Il est fourni la possibilité de tester l'API directement via une interface provenant du bundle. Pour chaque point d'entrée, il suffit de cliquer sur le lien Sandbox : un formulaire apparaît avec l'ensemble des champs qu'il est possible de renseigner.

Formulaire sandbox
Formulaire sandbox

Commandes pour exporter la documentation

Il est possible d'exporter la documentation avec les commandes suivantes :

$ bin/console api:doc:dump --format=json > doc.json
$ bin/console api:doc:dump --format=markdown > doc.md
bin/console api:doc:dump --format=html > doc.html

 

Je vous invite à lire la documentation officielle du NelmioApiDocBundle présentant bien d'autres fonctionnalités vous permettant d'aller plus loin, en particulier avec la configuration du bundle.

 

Rendez-vous au prochain et dernier chapitre discutant des alternatives au FOSRestBundle, concluant ce cours sur la construction d'API REST avec Symfony.

Exemple de certificat de réussite
Exemple de certificat de réussite