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.

Pour aller plus loin

Site officiel de Swagger

Site officiel de RAML

Site officiel d'API Blueprint