Recommandé
Contenu connexe
Tendances
Tendances (20)
Similaire à Swagger pour documenter votre REST API - présentation en français
Similaire à Swagger pour documenter votre REST API - présentation en français (20)
Swagger pour documenter votre REST API - présentation en français
- 1. Swagger Martin Yung 17 avril 2015
- 2. Objectifs Rappels sur les notions REST API Présentation de la norme Swagger Outils
- 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. 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. API REST = Application Programming Interface Contrat de service Formats de messages XML JSON Exemple USA.gov Supporté par APIgee Microsoft Azure API Management
- 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. Swagger 2.0 Sortie en septembre 2014 Supporte Markdown Un seul fichier : swagger.json par défaut
- 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
- 10. swagger-to-html
- 11. Swashbuckle
- 12. Comment décrire un endpoint Path /api/parametre/titre/descriptif {get/post} description parameters responses 200 404
- 13. Comment décrire un paramètre / une réponse parameters name in description schema type properties produit type : object valeurFaciale …
- 14. Ce que nous avons vu Décrire les endpoints avec la norme Swagger Utiliser les outils swagger-editor swagger-to-html Swashbuckle
- 16. Merci
Notes de l'éditeur
- 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