Difference between revisions of "VT2016 Swagger"
| (14 intermediate revisions by the same user not shown) | |||
| Line 3: | Line 3: | ||
*Sujet : Swagger |
*Sujet : Swagger |
||
*Auteur : Abdelaziz FOUNAS |
*Auteur : Abdelaziz FOUNAS |
||
| − | * |
+ | *Enseignants : Didier DONSEZ, Georges-Pierre BONNEAU |
=Résumé= |
=Résumé= |
||
| Line 9: | Line 9: | ||
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. |
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. |
||
| − | + | [[File:VT2016_Swagger_logo.png|1200px]] |
|
| + | =Les outils Swagger= |
||
| − | =Fonctionnement de Docker= |
||
| + | 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 : |
||
| − | Docker est une technologie qui permet de faire de la virtualisation dite par isolement. Le principe est celui des container : c'est un environnement complet qui est isolé du reste des processus. Les principales technologies utilisées pour parvenir à ces fins sont : |
||
| − | - cgroups : Cet utilitaire permet de créer des groupes de processus et de les gérer ensembles. Ses principales fonctionnalités sont la gestion de ressource par groupe de processus. |
||
| − | - LinuX Container (LXC) : Le but de LXC est de fournir un environnement d'exécution virtualisé, et non pas un système complet. De fait, le système virtualisé est le même que l'hôte. |
||
| + | *Swagger Core |
||
| − | =Les mécanismes de Docker= |
||
| + | 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. |
||
| − | Dans son fonctionnement, Docker distingue principalement 2 éléments afin de fournir une virtualisation : les images et les containers. Une image correspond à l'état d'un système, prêt à être utilisé. Une image va servir de base à un container, qui lui va représenter l'évolution d'une exécution de cette image, sans influencer celle-ci. Ainsi, les image et les container peuvent être rapproché des classes et objets en programmation objet. |
||
| + | *Swagger Codegen |
||
| − | Plusieurs moyen sont disponible pour avoir une image, des images ready to use sont disponible dans des "registry", comme le Docker Hub. Une autre possibilité est de créer sa propre image, avec un Dockerfile (ou Docker compose). Le principe est de choisir une image de base, et d'y ajouter les outils nécessaire à ses besoins. Toute les images existantes peuvent servir de base. Ci dessous, le Dockerfile de l'image Hello-World, créée par Docker : |
||
| − | <syntaxhighlight lang="text"> |
||
| − | #Extrait hello-world/Dockerfile |
||
| − | FROM scratch |
||
| − | COPY hello / |
||
| − | CMD [« /hello »] |
||
| − | </syntaxhighlight> |
||
| + | 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. |
||
| − | Le mot clé FROM indique le nom de l'image sur laquelle se baser. COPY, quant à lui, permet de copier du contenu directement dans l'image. Finalement, le mot clé CMD permet d'exécuter une commande au lancement d'un container basé sur l'image. Lancer cette image aura donc pour effet d'exécuter le programme "hello". |
||
| + | *Swagger UI |
||
| − | =Docker face aux VM= |
||
| + | 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. |
||
| − | Docker vient directement faire face aux machines virtuels. Son point fort est sa légèreté : Docker n'a pas besoin d'un OS invité complet vu qu'il se base sur celui de l'hôte. |
||
| + | *Swagger Editor |
||
| − | [[File:CaaS2016-VM.png|500px]] |
||
| − | [[File:CaaS2016-Docker.png|500px]] |
||
| + | 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. |
||
| − | Ci-dessus, à gauche, le principe de fonctionnement des machine virtuelles. Un hypervisor va venir gérer les ressources du système hôte pour les systèmes invités. Pour faire fonctionner une application, un système complet est nécessaire. A droite, le principe de fonctionnement de Docker. Docker se base sur le système hôte, il n'y a donc pas besoin d'un système invité complet. Le Docker Engine rempli donc le même rôle que l'hypervisor pour les VM. |
||
| − | =Les |
+ | =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 Containers as a Service sont une application de Docker dans le cloud. Les containers vont être déployés sur des machines distantes dans le cloud. Le principal avantage de ce service est la portabilité : le container en local sera basé sur la même image que le container distant. De ce fait, il n'y aura aucune mauvaise surprise dû au matériel ou à la configuration de la machine dans le cloud. |
||
| + | =Les alternatives à Swagger= |
||
| − | Un autre avantage est de pouvoir séparer complètement la partie développement de la partie déploiement : le développeur ne se soucie plus que du développement et de la construction de l'image, alors que d'autres équipes vont se charger du déploiement sans se soucier de la configuration de l'image ni de ce qu'elle contient. |
||
| + | |||
| + | 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.<br> |
||
| + | Les moins : il manque des outils niveau code. |
||
| + | |||
| + | *API Blueprint |
||
| + | |||
| + | Les plus : facile à comprendre et à écrire.<br> |
||
| + | Les moins : difficile à installer. |
||
=Pour aller plus loin= |
=Pour aller plus loin= |
||
Latest revision as of 09:48, 14 October 2016
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.