Swagger est un framework offrant un ensemble d’outils permettant de designer et documenter ses API. Il propose par exemple une interface graphique facilitant l’exploration et le test des API que vous mettez à disposition par vos consommateurs. Swagger une implémentation Open Source basé sur la spécification OpenAPI. Découvrez davantage d’informations sur Swagger et la spécification OpenAPI dans cet article.
Swagger et la spécification OpenAPI
Swagger fut lancé en 2011 par une startup (Wordnik). Pendant le développement de leurs produits, cette équipe s’est rendu compte du gain de temps que pourrait amener un outil automatique pour générer automatiquement une documentation pour ses API. Ils ont donc mis en place un Framework basé sur du JSON pour permettre aux développeurs de designer et documenter leurs API en synchronisation avec leur code.
En parallèle au Framework, l’équipe instaure une spécification Swagger qui définit ainsi le standard à respecter. Ce projet est devenu une référence pour le design et la description des API REST. De nombreux géants de l’informatique y contribue, comme IBM, Microsoft ou encore Google. En 2016, le programme prend le nom d’OpenAPI Specification (OAS) et passe désormais sous la gouvernance de la fondation Linux.
Avec la spécification OpenAPI les développeurs d’API peuvent maintenir une documentation au même endroit que le code de l’API. Il est également à noter que cette spécification permet une interprétation des API par des algorithmes grâce à l’utilisation d’un langage structuré. Ainsi, une API correctement décrite avec la spécification OpenAPI permettra à ses consommateurs une compréhension et une intégration plus facile dans leurs applications.
Le framework Swagger se construit autour de cette spécification et se compose de différents outils :
- Swagger Editor, un éditeur en ligne pour concevoir la description OpenAPI de vos API.
- Swagger UI, une interface graphique pour afficher la documentation de vos API à partir de la description OpenAPI conçue.
- Swagger Codegen, un générateur de librairies facilitant l’intégration de vos API pour vos consommateurs à partir de sa description OpenAPI.
Contenu d’un document OpenAPI
En utilisant la spécification OpenAPI et Swagger pour le design de vos API, vous pouvez générer des documentations interactives et des exemples de code dans plusieurs langage pour intégrer les API. Pour désigner vos API, les langages supportés sont JSON et YAML.
La spécification définit diverses étiquettes permettant de présenter des informations sur votre API :
- URL d’appel et opérations permises (GET, POST, PUT, etc.).
- les paramètres d’entrées et de sortie des vos API.
- les méthodes d’authentification utilisées.
Il existe plusieurs possibilités pour mettre en place Swagger sur vos API :
- Si vous maitrisez la structure des langages JSON et YAML, la mise en place de Swagger peut se faire avec un simple éditeur de texte. A noter que l’édition au format YAML est plus facile que l’édition au format JSON. Vous pouvez également vous appuyer sur Swagger Editor, un outil en ligne pour créer les fichiers nécessaires à Swagger.
- Lors du développement de l’API, il est possible de la décrire directement dans le code en y ajoutant les informations définies par Swagger. En cas d’évolution de l’API, sa documentation Swagger sera ainsi plus facile à mettre à jour. En effet, elle sera localisée au même niveau que le code de l’API.
Swagger Editor pour décrire vos API
Utiliser un simple programme pour construire un document OpenAPI ne constitue plus une difficulté. Au contraire, tout semble plus aisé. On peut trouver un éditeur Swagger gratuit et disponible en ligne. Ce logiciel vous offre de nombreuses fonctions incluant l’auto-complétion. Il dispose d’un éditeur à gauche pour le design de votre API, mais aussi d’une fenêtre à droite vous servant d’aperçu. C’est dans cette fenêtre que s’affiche la documentation interactive sur l’API en conception.
Ayant désigné votre API avec OpenAPI, la génération de la documentation interactive est possible automatiquement. Il est également possible de générer des exemples d’intégration de l’API dans plusieurs langages de programmation.
Swagger dans le code de vos API
Il existe aujourd’hui plusieurs librairies disponibles dans plusieurs langages qui permettent d’inclure une description via Swagger de vos API. Vous pouvez en retrouver une liste sur le site de Swagger.
