Documenter l’API REST Symfony avec NelmioAPIDoc

Grâce à NelmioAPIDoc, il est possible de générer une documentation de type Swagger idéale pour une API REST. Le bundle récupère l’annotation ApiDoc() située en haut des contrôleurs et génère une belle documentation disponible en ligne.

La section suivante présente comment utiliser cette annotation.

Exemple d’annotation @ApiDoc

Le code suivant démontre comment spécifier la route de la ressource, une description, les données d’entrées et les codes de statut (statusCode) utilisés .

<?php
use Nelmio\ApiDocBundle\Annotation\ApiDoc;

/**
* @ApiDoc(
* resource="/api/contact",
* description="Sends a contact email",
* input={
*   "class"="Acme\Bundle\ApiBundle\Form\ContactType",
* },
* statusCodes={
*     200="Successful",
*     403="Validation errors"
*   },
* )
* @ParamConverter("contact", class="Acme\Bundle\ApiBundle\Model\Contact", 
*                            converter="fos_rest.request_body")
* @Post("/contact")
*/
public function postContactAction(Request $request, Contact $contact)
{

}

Exemple de documentation Swagger

Configuration pour NelmioApiDoc

nelmio_api_doc:
    name:                   API doc title
    sandbox:
        enabled:            false
        endpoint:           http://localhost:8000/api/
        accept_type:        application/json
        body_format:
            formats:        null
            default_format: json
        request_format:
            formats:
                json:       application/json
                xml:        null
            method:         accept_header
            default_format: json
        authentication:
            name:           bearer
            delivery:       header
    cache:
        enabled:            false
        file:               '%kernel.cache_dir%/api-doc.cache'

Les parsers

Le bundle doit donc lire le code afin de créer la documentation correspondante. Pour se faire, des parsers doivent être utilisés. Dans l’exemple suivant, le parser JmsMetadataParser est spécifié dans l’annotation. Cela permet de lire les configurations de votre serializer JMS.

/*  
*  output= {
*     "class"="Acme\Bundle\ApiBundle\Entity\Comment",
*     "groups"={"comment"},
*     "parsers"={"Nelmio\ApiDocBundle\Parser\JmsMetadataParser"},
*  },
*/

D’autres parsers sont disponibles. Voici un lien vers la référence officielle sur GitHub :

https://github.com/nelmio/NelmioApiDocBundle/tree/master/Parser