Présentation de swagger
Pour résumer en une phrase ce qu’est Swagger, on peut dire que c’est un ensemble d’outils pour aider les développeurs dans la conception, le build, la documentation et la consommation d’API.
En 2010, Swagger n’était qu’une spécification open source pour construire des API REST. A cela est venu se greffer divers outils, également open source, pour aider à implémenter et visualiser les API; on parle là de Swagger UI, Swagger Editor et Swagger Codegen.
En 2015, le projet Swagger est récupéré par Smartbear Software et la spécification swagger est renommée OpenAPI.
Les différentes solutions
Comme évoqué plus haut, il existe plusieurs outils pour aider à l’implémentation des API. En voici une brève explication.
Concevez-les avec Swagger Editor
Swagger Editor est un outil composé d’un éditeur et d’un visualisateur. L’éditeur permet de définir ses API au format yaml et le visualisateur offre une vue interactive de ce qui a été saisi dans l’éditeur.
Swagger Editor
Build avec Swagger Codegen
Swagger Codegen est un outil permettant de générer une librairie d’API en fournissant une spécification OpenAPI.
Documentez-les avec Swagger UI
Swagger UI est l’interface graphique permettant de visualiser et d’interagir avec ses API.
Elle offre ainsi la possibilité de les tester facilement et de les rendre plus accessible pour le client.
Liste des API
Interaction avec l’API
Avantages
Il y a plusieurs avantages à utiliser Swagger, les principaux étant :
- La génération automatique de la documentation à partir du code.
- Tout changement dans le code met à jour automatiquement la documentation; les deux sont donc étroitement liés.
- Gain de temps et donc de qualité. Le développeur n’a plus besoin de s’attarder sur la documentation, il a donc plus de temps à consacrer au développement de ses API.
La documentation de vos API
Nous allons ici nous consacrer à la documentation des API. Nous allons voir la façon d’implémenter celle-ci pour vos API.
Comment ?
Pour documenter une API, rien de plus simple, il suffit de passer par un fichier YAML ou JSON. Dans la suite de cet article nous allons utiliser le YAML. Je précise également que ce qui va suivre dans cet article ne contient pas une liste détaillée de toutes les sections et clés à utiliser pour une documentation complète, mais il y sera détaillé les plus utiles. Pour une description complète, je vous invite à vous rendre sur la documentation en ligne de Swagger https://swagger.io/docs/specification/basic-structure/
En premier lieu il faut indiquer la version de la spécification OpenAPI que l’on souhaite utiliser.
Une section “info” permet d’indiquer les informations de l’API. Les clés “title”, “description” et “version” peuvent être utilisées pour cela.
La section “server” permet d’indiquer les informations relatives aux serveurs, notamment l’url à utiliser et une courte description. Cela se fait au travers des clés “url” et “description”.
Ensuite vient la section “path”. C’est dans celle-ci que l’on va lister les différents endpoints et les méthodes HTTP associées (également appelée “opérations”). Pour chaque opération, il est possible d’indiquer, entre autres, un résumé, une description, des paramètres et les différentes réponses attendues (code et contenu).
Pour ce qui est des paramètres de l’API, ceux-ci peuvent être envoyés dans l’url (/users/{userId} ou /users?role=admin) ou via les Headers ou des cookies. Il est possible de le préciser dans la documentation en plus d’autres éléments tels qu’une description ou si le paramètre est optionnel ou non. Les clés “in”, “name”, “schema”, “required” et descripion sont à utiliser.
Si l’opération envoie un body avec la requête, il est possible de le documenter grâce à la clé “requestBody”
En ce qui concerne les réponses possibles, elles peuvent être toutes documentées sous la clé “responses” en précisant les différents codes attendus. Les clés “description” et “content” permettent respectivement d’apporter une description de la réponse et du contenu que celle-ci doit avoir.
Et enfin, si une authenthification est requise pour accéder à l’API, les sections “securitySchemes” et “security” sont à utiliser pour le documenter.
Etant développeur Symfony 5, il m’est arrivé d’utiliser cette solution pour documenter une API. Pour cela, en me basant sur la documentation de Symfony, j’ai utilisé le bundle NelmioApiDocBundle.
Pour apporter des informations globales sur l’API, il est possible de passer par le fichier de configuration du bundle (app/config/config.yml pour un projet Symfony en version 3 et config/packages/nelmio_api_doc.yaml pour un projet Symfony en version 4).
Pour documenter les routes, j’ai utilisé des SwaggerPHP annotations. Pour plus de détails sur celles-ci, je vous invite à consulter la documentation.
Exemple
Voici un exemple illustrant les propos du paragraphe précédent.
Nicolas D – Développeur Symfony
📌 Nous espérons que ce sujet vous a intéressé, retrouvez tous nos autres articles et si vous souhaitez en savoir plus sur des sujets spécifiques en développement informatique Prestashop, Symfony, ainsi que sur notre activité d’agence digitale, n’hésitez pas à nous contacter !
