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

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

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

9. swagger-editor

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

15. Resources https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md https://www.nuget.org/packages/swashbuckle

16. Merci 