SwaggerMartin Yung17 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 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.

REST

= Representational state transfer Architecture Client-serveur Sans état (stateless) Avantage

Respecte le standard HTTP (verbes : GET, POST…) Plus simple, moins verbose que SOAP

API REST

= Application Programming Interface Contrat de service Formats de messages

XML JSON

Exemple USA.gov

Supporté par APIgee Microsoft Azure API Management

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é

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) Ecrire les codes pour les controllers et modèles de vue (design

pattern MVVM) Utiliser le nuget Swashbuckle

swagger-editor

swagger-to-html

Swashbuckle

Comment décrire un endpoint

Path /api/parametre/titre/descriptif

{get/post} description parameters responses

200 404

Comment décrire un paramètre / une réponse

parameters name in description schema

type properties

produit type : object

valeurFaciale …

Ce que nous avons vu

Décrire les endpoints avec la norme Swagger Utiliser les outils

swagger-editor swagger-to-html Swashbuckle

Resources

https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md

https://www.nuget.org/packages/swashbuckle

Merci