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

837 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
837
Sur SlideShare
0
Issues des intégrations
0
Intégrations
30
Actions
Partages
0
Téléchargements
7
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 

    ×