Upload
martin-yung
View
1.564
Download
3
Embed Size (px)
Citation preview
SwaggerMartin Yung17 avril 2015
Objectifs
Rappels sur les notions REST API
Présentation de la norme Swagger Outils
La valeur d'un objet bien conçu : c’est quand il y a un ensemble riche de capacités que les personnes qui l'utilisent peuvent faire des choses que le concepteur n'a jamais imaginé. par Don Norman
The value of a well designed object is when it has such a rich set of affordances that the people who use it could do things that the designer never imagined.
REST
= Representational state transfer Architecture Client-serveur Sans état (stateless) Avantage
Respecte le standard HTTP (verbes : GET, POST…) Plus simple, moins verbose que SOAP
API REST
= Application Programming Interface Contrat de service Formats de messages
XML JSON
Exemple USA.gov
Supporté par APIgee Microsoft Azure API Management
Qu’est-ce que Swagger ?
Grammaire JSON/YAML Décrit une API REST Equivalent de WSDL pour REST Technologies supportées : .NET, Java, NodeJS… Alternatives
Aucun standard s’impose WADL (Web Application Description Language)
Soumis à W3C par SUN mais non standardisé
Swagger 2.0
Sortie en septembre 2014 Supporte Markdown Un seul fichier : swagger.json par défaut
Comment utiliser ?
API First Utiliser un éditeur Swagger Générer la documentation en HTML
Code First (.NET) Ecrire les codes pour les controllers et modèles de vue (design
pattern MVVM) Utiliser le nuget Swashbuckle
swagger-editor
swagger-to-html
Swashbuckle
Comment décrire un endpoint
Path /api/parametre/titre/descriptif
{get/post} description parameters responses
200 404
Comment décrire un paramètre / une réponse
parameters name in description schema
type properties
produit type : object
valeurFaciale …
Ce que nous avons vu
Décrire les endpoints avec la norme Swagger Utiliser les outils
swagger-editor swagger-to-html Swashbuckle
Resources
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md
https://www.nuget.org/packages/swashbuckle
Merci