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

1 356 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
0 commentaire
1 j’aime
Statistiques
Remarques
  • Soyez le premier à commenter

Aucun téléchargement
Vues
Nombre de vues
1 356
Sur SlideShare
0
Issues des intégrations
0
Intégrations
14
Actions
Partages
0
Téléchargements
17
Commentaires
0
J’aime
1
Intégrations 0
Aucune incorporation

Aucune remarque pour cette diapositive
  • Donald Arthur "Don" Norman (born December 25, 1935) is the director of The Design Lab at University of California, San Diego (cf http://en.wikipedia.org/wiki/Don_Norman)
  • http://www.usa.gov/About/developer-resources/federal-agency-directory/interactivedoc.shtml#!/contacts

    Séparation de responsabilité
    Front : HTML, CSS, JavaScript (AngularJS)
    Back : .NET, NodeJS, PHP
    http://azure.microsoft.com/en-us/documentation/articles/api-management-howto-import-api/
  • https://github.com/swagger-api/swagger-spec/tree/master/versions
  • swagger-to-html : https://www.npmjs.com/package/swagger-to-html
    Swashbuckle : https://www.nuget.org/packages/swashbuckle
  • Installer NodeJS
    Lancer dans l’invité de commande : git clone https://github.com/swagger-api/swagger-editor.git
    cd swagger-editor
    npm start
  • Installer NodeJS
    Lancer dans l’invité de commande : npm install –g swagger-to-html
    swagger-to-html swagger.json c:\output
  • 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 

    ×