VT2016 Swagger
Présentation
- Sujet : Swagger
- Auteur : Abdelaziz FOUNAS
- Enseignants : Didier DONSEZ, Georges-Pierre BONNEAU
Résumé
Swagger est une technologie permettant de faire le développement d'API REST. Elle permet notamment de créer la documentation, de gérer les tests et de faire la génération aussi bien côté serveur que du côté client de ces API REST. Cette technologie est OpenSource et est très utilisée, c'est pourquoi elle fonctionne avec beaucoup de différents langages.
Les outils Swagger
Beaucoup d'outils et modules ont été créé pour Swagger vu la taille de sa communauté. Ici, sont présenté les principaux éléments de cet ensemble :
- Swagger Core
Swagger Core est l'implémentation de Swagger pour Java. C'est un ensemble de librairie Java permettant de générer et d'assimiler des définitions Swagger enregistrées dans un fichier spécial. Cet outil prend en charge JAX-RS et est indispensable pour l'utilisation de Swagger sous Java.
- Swagger Codegen
Swagger Codegen est un outil permettant de générer les API soit côté serveur soit côté client sur un grand nombre de langage, tout cela à partir d'un fichier de définition Swagger.
- Swagger UI
Swagger UI est un ensemble de fichier HTML, JS et CSS formant un site permettant de faire à la fois l'affichage et l'interaction avec une API REST à partir d'un fichier de définition Swagger. Ce site peut servir à la fois de documentation, d'apprentissage et de test.
- Swagger Editor
Swagger Editor est un outil en ligne permettant de prévisualiser et de vérifier un fichier de définition Swagger. Ainsi on peut savoir si le fichier en question est correct. Ensuite, on peut soit télécharger le fichier ainsi créé soit en générer soit le côté serveur, soit le côté client tout cela très simplement.
Les formats Swagger
Swagger est centré sur le fichier de définition Swagger. Ce fichier est formalisé dans un méta-langage. Pour Swagger, c'est soit en JSON soit YAML. YAML est un peu plus évolué que JSON mais permet la même chose. L'avantage de YAML est qu'il est plus compréhensible pour l'Homme car plus naturel, et il contient quelques fonctionnalités de plus comme la capacité de pouvoir pointer un autre élément dans le fichier YAML.
Les alternatives à Swagger
Il y a plusieurs alternatives à Swagger, les deux plus grosses solutions sont RAML ou API Blueprint.
- RAML
Les plus : la construction des metadatas est avancée ce qui permet le fonctionnement sur d'autres architectures n'adhérant pas complètement à la vision REST comme RPC.
Les moins : il manque des outils niveau code.
- API Blueprint
Les plus : facile à comprendre et à écrire.
Les moins : difficile à installer.