swagger pour documenter votre rest api - présentation en français
TRANSCRIPT
![Page 1: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/1.jpg)
SwaggerMartin Yung17 avril 2015
![Page 2: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/2.jpg)
Objectifs
Rappels sur les notions REST API
Présentation de la norme Swagger Outils
![Page 3: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/3.jpg)
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.
![Page 4: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/4.jpg)
REST
= Representational state transfer Architecture Client-serveur Sans état (stateless) Avantage
Respecte le standard HTTP (verbes : GET, POST…) Plus simple, moins verbose que SOAP
![Page 5: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/5.jpg)
API REST
= Application Programming Interface Contrat de service Formats de messages
XML JSON
Exemple USA.gov
Supporté par APIgee Microsoft Azure API Management
![Page 6: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/6.jpg)
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é
![Page 7: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/7.jpg)
Swagger 2.0
Sortie en septembre 2014 Supporte Markdown Un seul fichier : swagger.json par défaut
![Page 8: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/8.jpg)
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
![Page 9: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/9.jpg)
swagger-editor
![Page 10: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/10.jpg)
swagger-to-html
![Page 11: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/11.jpg)
Swashbuckle
![Page 12: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/12.jpg)
Comment décrire un endpoint
Path /api/parametre/titre/descriptif
{get/post} description parameters responses
200 404
![Page 13: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/13.jpg)
Comment décrire un paramètre / une réponse
parameters name in description schema
type properties
produit type : object
valeurFaciale …
![Page 14: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/14.jpg)
Ce que nous avons vu
Décrire les endpoints avec la norme Swagger Utiliser les outils
swagger-editor swagger-to-html Swashbuckle
![Page 15: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/15.jpg)
Resources
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md
https://www.nuget.org/packages/swashbuckle
![Page 16: Swagger pour documenter votre REST API - présentation en français](https://reader036.vdocuments.us/reader036/viewer/2022062503/58e85b971a28ab78478b6665/html5/thumbnails/16.jpg)
Merci