Documentation d’API automatique sur Symfony avec NelmioApiDoc

Plop à tous,

De retour en dev PHP, depuis quelques temps je me retrouve à faire des API sur Symfony (voir mon article sur FosRestBundle). Je cherchais un moyen d’automatiser la doc des API, mais aussi de pouvoir les tester côtés back sans avoir à faire de front, tout en ayant la possibilité d’utiliser des token d’authentifications, …

C’est justement ce que permet NelmioApiDoc !!

L’installation est simple … suffit de suivre la doc de symfony !! [RTFM!!]. Le but de cette article est juste de  parler des capacités de l’outils … de nombreux sites [1,2,…] explique son utilisation, aussi je n’en parlerais pas (vous trouverez une petite liste des tweaks trouvés aux cours de mes expérimentations plus bas).

La documentation quand à elle est très simple : elle se fait via les commentaires de type @ApiDoc.

Il est ainsi possible de définir les types d’entrée/sorties à la façon de swagger et aussi d’automatiser les get/post/put/delete avec les bons paramètres dans l’url et en body!!

Il est aussi possible de rajouter les filtres, et autre pré-requis …

La Sandbox (utilisation d’un token d’authentification).

Pour utiliser un token d’oauth2, la configuration est plutôt simple :

nelmio_api_doc:
    sandbox:
        request_format:
            formats:
                json: application/json
            method: accept_header
        authentication:
            delivery: http
            type:     bearer

Il sera désormais possible de spécifier votre token pour vous authentifier sur votre api depuis ApiDoc.

Forcer l’utilisation du format JSON lors des post/put.

nelmio_api_doc:
        body_format:
            formats: [ json ]
            default_format: json

Séparer les urls des « ressources »

L’idée est de séparer des actions simples, des actions propres aux entités.

    /**
     * @ApiDoc(
     *    resource=true
     * )
    */

Filtrage des entités sur les entrées/sorties

Ici, il est possible de fournir sur un même objet, plusieurs type de formattage en entrée comme en sortie en utilisant les vues.

    /**
     * @ApiDoc(
     *  input={"class"="User","groups"={"default","password"}},
     *  output="User",
     * )   
     */

Voilà voila, … c’était un peu l’ensemble des fonctionnalités avancées que j’ai pu trouver jusque là.