Swagger
Martin Yung
17 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 peuv...
REST
 = Representational state transfer
 Architecture Client-serveur
 Sans état (stateless)
 Avantage
 Respecte le st...
API REST
 = Application Programming Interface
 Contrat de service
 Formats de messages
 XML
 JSON
 Exemple
 USA.gov...
Qu’est-ce que Swagger ?
 Grammaire JSON/YAML
 Décrit une API REST
 Equivalent de WSDL pour REST
 Technologies supporté...
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)
 Ecri...
swagger-editor
swagger-to-html
Swashbuckle
Comment décrire un endpoint
 Path
 /api/parametre/titre/descriptif
 {get/post}
 description
 parameters
 responses
...
Comment décrire un paramètre /
une réponse
 parameters
 name
 in
 description
 schema
 type
 properties
 produit
...
Ce que nous avons vu
 Décrire les endpoints avec la norme Swagger
 Utiliser les outils
 swagger-editor
 swagger-to-htm...
Resources
 https://github.com/swagger-api/swagger-
spec/blob/master/versions/2.0.md
 https://www.nuget.org/packages/swas...
Merci 
Prochain SlideShare
Chargement dans…5
×

Swagger pour documenter votre REST API - présentation en français

3 013 vues

Publié le

Voici une présentation que j'ai faite auprès d'une équipe de développement sur la norme Swagger, équivalent du WSDL pour les services REST

Publié dans : Technologie
  • Soyez le premier à commenter

Swagger pour documenter votre REST API - présentation en français

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

×