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 .
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
<?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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
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.
|
1 2 3 4 5 6 7 |
/* * 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
Laisser un commentaire
Participez-vous à la discussion?N'hésitez pas à contribuer!