Introduzione all'uso di Swagger per la documentazione dei servizi WebAPI di ASP.NET

1. Tutti per uno
e Swagger per tutti!
NicolòCarandini
n.carandini@mahiz.it
www.mahiz.it

2. Nicolò Carandini
n.carandini@mahiz.it
Session Tuning
Web Services e REST API
Cos’è Swagger e a cosa serve
Documentazione delle API
Tools di generazione
Integrazione con Azure Web Services
Q&A
Agenda

3. Nicolò Carandini
n.carandini@mahiz.it
Che differenza c’è tra HTTP e HTML ?
Che differenza c’è tra Web App e Web Service ?
Chi è Tim Berners-Lee?
Cos’è un servizio RESTful
Session tuning

4. Nicolò Carandini
n.carandini@mahiz.it
Iniziamo dal World Wide Web

5. Nicolò Carandini
n.carandini@mahiz.it
Il Web usa HTTP e HTML

6. Nicolò Carandini
n.carandini@mahiz.it
HTTP (Hypertext Transfer Protocol)

7. Nicolò Carandini
n.carandini@mahiz.it
Uniform Resource Locator

8. Nicolò Carandini
n.carandini@mahiz.it
Web App Vs. Web Service

9. Nicolò Carandini
n.carandini@mahiz.it
Lo conoscete?
Quiz Time

10. Nicolò Carandini
n.carandini@mahiz.it
 Ha scritto una tesi di dottorato dal titolo:
Architectural Styles and the Design of
Network-based Software Architectures
nella quale descrive una metodologia di
scrittura dei servizi chiamata REST
(Representational State Transfer).
 E’ uno dei principali autori delle specifiche
dell‘HTTP (Hypertext Transfer Protocol)
presso il W3C, dove ha lavorato con Tim
Berners-Lee, meglio noto come
"Father of Web".
Roy Fielding

11. Nicolò Carandini
n.carandini@mahiz.it
Client–Server
Uniform interface
Stateless
Cacheable
Layered system
REpresentational State Transfer

12. Nicolò Carandini
n.carandini@mahiz.it
Utilizza i metodi HTTP (Get, Post, Put, Delete, …) per
identificare l’azione.
Usa l’URL (Uniform Resource Locator) per identificare la
risorsa e i parametri
Usa il body per i dati inviati o ricevuti, tipicamente in
formato XML o JSON
REST: Uniform Interface

13. Nicolò Carandini
n.carandini@mahiz.it
REST: Stateless

14. Nicolò Carandini
n.carandini@mahiz.it
 Un servizio web che utilizza i metodi HTTP e implementa i principi
REST viene chiamato RESTful.
 ASP .NET WebAPI è un ottimo strumento di realizzazione di servizi
RESTful.
Attenzione:
 Non tutti i servizi web di tipo REST sono RESTful, si veda ad esempio
il concetto di discoverability:
If you are just using Rest for pretty urls mapped to CRUD operations that a consumer
must have prior knowledge of and calls according to a well known contract, Roy Fielding
would deem it not truly RESTful.
RESTful Web Service

15. Nicolò Carandini
n.carandini@mahiz.it
Per tener traccia del tempo impiegato dai vari developer
per il completamento dei task.
Basato sul cloud.
Verticalmente scalabile.
Utilizzabile da una pluralità di device.
Facilmente integrabile.
Un esempio di Web Service: TaskTimer

16. Nicolò Carandini
n.carandini@mahiz.it
TaskTimer: il modello

17. Nicolò Carandini
n.carandini@mahiz.it
TaskTimer: l’architettura del progetto
• Servizio RESTful
TaskTimer.WebAPI
• Data access layer e Business logic
TaskTimer.Data
• Modello ad oggetti e funzionalità di base
TaskTimer.Core

18. Nicolò Carandini
n.carandini@mahiz.it
La chiamata REST viene instradata al metodo del controller che implementa il
percorso contenuto nella URL:
ASP.NET WebAPI: Routing
http://tasktimer.com/api/v1/usersGET
UsersController

19. Nicolò Carandini
n.carandini@mahiz.it
Una chiamata REST è formata dal Verbo e dal Path e dai dati eventualmente
contenuti nei Query parameters, negli Headers e nel Body content.
I dati vengono utilizzati per valorizzare i parametri del metodo associato
attraverso un’operazione di binding:
ASP.NET WebAPI: Binding
http://tasktimer.com/api/v1/customers/123PUT
Controller
{
CompanyName : "Fiat"
}
Body
DTO

20. Nicolò Carandini
n.carandini@mahiz.it
L’ Application Programming Interface di un Web Service è definita da:
 L’elenco delle richieste e delle relative possibili risposte
 Per ciascuna di esse la descrizione dei dati, che possono essere
obbligatori o opzionali.
 Per quanto REST usi un meccanismo standard per effettuare le
richieste e ricevere le risposte, occorre comunque avere a
disposizione la documentazione delle API.
Web Service API

21. Nicolò Carandini
n.carandini@mahiz.it
Documentazione delle API
inizialmente viene fatta
poi diventa incompleta
e alla fine è spesso inesatta

22. Nicolò Carandini
n.carandini@mahiz.it
 Un linguaggio "JSON like" dedicato alla descrizione delle Web
Service API.
 E’ una specifica Open Source, ed è diventato lo standard di fatto del
mercato per la descrizione delle RESTful API.
 Intorno a questo "standard industriale" sono stati sviluppati molti
tools di:
 Generazione automatica del documento Swagger
 Generazione della documentazione dell’API
 Generazione del modello di classi DTO
Swagger

23. Nicolò Carandini
n.carandini@mahiz.it
Swagger UI è un insieme di template HTML, codice Javascript e CSS che
generano dinamicamente una documentazione dell’API fruibile da Web a partire
da un documento Swagger.
Swagger Ui

24. Nicolò Carandini
n.carandini@mahiz.it
 Fornito tramite NuGet Package.
 Genera automaticamente il documento Swagger.
 Contiene al suo interno Swagger-ui.
 Genera lo schema dei dati delle API tramite Reflection.
 Consente la personalizzazione della documentazione Swagger
generata e della Swagger UI.
 Utilizza e include automaticamente i commenti Xml del codice.
 Supporta la descrizione degli schemi ApiKey, Basic Auth and
OAuth2, incluso il supporto UI per l’Implicit OAuth2 flow.
Swashbuckle

25. Nicolò Carandini
n.carandini@mahiz.it
1. Abilitare la generazione della documentazione XML:
2. Abilitare l’uso della documentazione XML in Swagger UI:
Includere la documentazione XML del codice

26. Nicolò Carandini
n.carandini@mahiz.it
Demo: Swagger e Swagger UI con Swashbuckle

27. Nicolò Carandini
n.carandini@mahiz.it
 Lato Client, un’app usa HTTP per comunicare col servizio Web.
 I dati vengono scambiati attraverso la serializzazione /
deserializzazione di classi DTO (Data Transfer Object), composte di
sole proprietà, senza metodi.
 La generazione di questo modello "anemico" è noiosa e molto
ripetitiva.
 Utilizzare le risposte serializzate per generare le classi DTO non è
consigliabile.
Utilizzare un Web Service RESTful

28. Nicolò Carandini
n.carandini@mahiz.it
Qualunque operazione effettuabile su Azure è disponibile
tramite un servizio web di tipo REST.
Le API sono documentate con Swagger
Un generatore automatico consente, a partire dalla
documentazione scritta in Swagger, di produrre gli SDK di
Azure nei vari linguaggi.
Questo consente di avere tutti gli SDK sempre aggiornati
all’ultima versione delle Azure API.
Un caso d’uso: Azure e Swagger

29. Nicolò Carandini
n.carandini@mahiz.it
E’ un tool per la generazione di librerie client per l’accesso
di servizi web RESTful.
Come input viene utilizzato il documento che descrive le
REST API scritto in formato Swagger.
E’ in grado di generare librerie in diversi linguaggi, come
C#, Javascript, ecc.
AutoRest

30. Nicolò Carandini
n.carandini@mahiz.it
1. Scaricare il generatore AutoRest con il NuGet Package Manager.
2. Creare una cartella di lavoro (ad esempio AutoRest).
3. Copiare dal package "autorest.x" il file "autorest.x.nupkg" e la cartella "Tools"
nella cartella di lavoro.
4. Copiare nella cartella di lavoro il file swagger.json che descrive l’API del
servizio web
5. Sempre nella cartella di lavoro, creare il file batch di generazione:
6. Eseguire il file batch.
Come utilizzare AutoRest per generare il codice cliente

31. Nicolò Carandini
n.carandini@mahiz.it
1. Scaricare l’AutoRest client con il NuGet Package Manager.
2. Copiare il codice generato da AutoRest nel progetto.
3. Istanziare il servizio ed utilizzare le classi proxy per effettuare le richieste e
gestire le risposte:
Come utilizzare AutoRest nell’app cliente

32. Nicolò Carandini
n.carandini@mahiz.it
Swagger per tutti
AutoRESTSwashBuckle
HTTP Rest Comunication

33. Nicolò Carandini
n.carandini@mahiz.it
Azure App Service

34. Nicolò Carandini
n.carandini@mahiz.it
• Visual Editor per la creazione del flusso di elaborazione
• Un elevato numero di template disponibili
• Supporto per i più popolari servizi SaaS
• Può utilizzare custom API app fatte da noi
• BizTalk APIs for per scenari di integrazione evoluti
Logic Apps

35. Nicolò Carandini
n.carandini@mahiz.it
Il servizio viene utilizzato
dagli utenti tramite un sito
web e consente di fare
l'upload dei file da
stampare in 3D, scegliere
uno "stampatore"
dall'elenco di quelli più
vicini e ordinarne la stampa.
Esempio d’uso: 3D Hubs

36. Nicolò Carandini
n.carandini@mahiz.it
Per ogni ordine dev'essere svolta tutta una serie di attività, quali
ad esempio:
Elaborare alcuni dati come volume e dimensioni dell'oggetto da
stampare, a partire dai file di stampa ricevuti;
Recuperare dal database l'elenco degli "stampatori" ordinati per
distanza geografica dalla posizione in cui si trova il richiedente;
Quando il cliente eventualmente completa l'ordine, inviare i file
dati allo stampatore insieme a una email che lo avverta del
nuovo ordine di lavorazione da eseguire;
Quando lo stampatore comunica di aver terminato il lavoro,
avvertire il cliente tramite email.
Flusso di lavoro

37. Nicolò Carandini
n.carandini@mahiz.it
Per eseguire i diversi passi del flusso di lavoro è possibile
appoggiarsi ad altri servizi, come in questo caso:
NetFabb
per la verifica validità e autoriparazione dei file di stampa
Twilio
per l’invio di SMS
SQL Server
per la gestione dei dati
Collaborare con servizi esterni

38. Nicolò Carandini
n.carandini@mahiz.it
Utilizzare Logic Apps per l’integrazione dei servizi

39. Nicolò Carandini
n.carandini@mahiz.it
Di connettori già pronti ce ne sono davvero tanti, sia
Microsoft che di terze parti:
Logic App Connectors

40. Nicolò Carandini
n.carandini@mahiz.it
Custom Connector (a.k.a. API App)

41. Nicolò Carandini
n.carandini@mahiz.it
Lab: Costuiamo la nostra prima Logic App

42. Nicolò Carandini
n.carandini@mahiz.it
Swagger
swagger.io
Swashbuckle
github.com/domaindrivendev/Swashbuckle
AutoRest
github.com/Azure/autorest
Azure Logic Apps
azure.microsoft.com/en-us/documentation/services/app-service/logic
Riferimenti

43. Nicolò Carandini
n.carandini@mahiz.it
Swagger and ASP.NET Web API - Part I: Adding Swagger to Web API project
www.wmpratt.com/swagger-and-asp-net-web-api-part-1
Creating Service Contract with AutoRest, Swagger and HAL
blog.kloud.com.au/2015/10/26/creating-service-contract-with-autorest-swagger-and-hal
Introduzione alle Azure Logic App
www.windowsazureitalia.com/articoli/windows-azure/introduzione-azure-logic-apps.aspx
Lab: My First Azure Logic App
http://1drv.ms/1KZ4qBU
Azure Logic App with simple API App with inputs and outputs
blogs.msdn.com/b/hosamshobak/archive/2015/03/31/logic-app-with-simple-api-app-with-inputs-and-outputs.aspx
Articoli