Post on 02-Jun-2020
presenta
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 - #wpc15it 1
Tutti per unoe Swagger per tutti!Nicolò Carandini – MVP Windows Development
n.carandini@mahiz.it – @TPCWare
Agenda
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 2
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 3
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 4
Iniziamo dal World Wide Web
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 5
Il Web usa HTTP e HTML
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 6
HTTP (Hypertext Transfer Protocol)
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 7
Uniform Resource Locator
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 8
Web App Vs. Web Service
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 9
Lo conoscete?
Quiz Time
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 10
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 11
• Client–Server
• Uniform interface
• Stateless
• Cacheable
• Layered system
REpresentational State Transfer
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 12
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 13
REST: Stateless
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 14
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 15
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 16
TaskTimer: il modello
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 17
• Servizio RESTful
TaskTimer.WebAPI
• Data access layer e Business logic
TaskTimer.Data
• Modello ad oggetti e funzionalità di base
TaskTimer.Core
TaskTimer: l’architettura del progetto
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 18
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/usersGETU
sers
Co
ntr
olle
r
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 19
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 atraversoun’operazione di binding:
ASP.NET WebAPI: Binding
http://tasktimer.com/api/v1/customers/123PUT
Co
ntr
olle
r
{ CompanyName : "Fiat"}
Bo
dy
DTO
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 20
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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 21
Documentazione delle API
inizialmente viene fatta
poi diventa incompleta
e alla fine è spesso inesatta
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 22
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 23
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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 24
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 25
1. Abilitare la generazione della documentazione XML:
2. Abilitare l’uso della documentazione XML in Swagger UI:
Includere la documentazione XML del codice
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 - #wpc15it 26
Demo: Swagger e Swagger UI con Swashbuckle
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 27
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 28
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 29
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 30
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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 31
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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 32
Swagger per tutti
AutoRESTSwashBuckle
HTTP Rest Comunication
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 - #wpc15it 33
• Code generation
• Client App
Demo: AutoRest
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 34
Azure App Service
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 35
Logic Apps
• 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
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 36
Demo: Custom API App
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 37
Demo: Logic App
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 - #wpc15it 38
Question Time
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 - #wpc15it 39
Swaggerswagger.io
Swashbucklegithub.com/domaindrivendev/Swashbuckle
AutoRestgithub.com/Azure/autorest
Azure Logic Appsazure.microsoft.com/en-us/documentation/services/app-service/logic
Riferimenti
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 - #wpc15it 40
Swagger and ASP.NET Web API - Part I: Adding Swagger to Web API projectwww.wmpratt.com/swagger-and-asp-net-web-api-part-1
Creating Service Contract with AutoRest, Swagger and HALblog.kloud.com.au/2015/10/26/creating-service-contract-with-autorest-swagger-and-hal
Introduzione alle Azure Logic Appwww.windowsazureitalia.com/articoli/windows-azure/introduzione-azure-logic-apps.aspx
Azure Logic App with simple API App with inputs and outputsblogs.msdn.com/b/hosamshobak/archive/2015/03/31/logic-app-with-simple-api-app-with-inputs-and-outputs.aspx
Articoli
Contatti OverNet Education
OverNet Educationinfo@overneteducation.it
www.overneteducation.it
Tel. 02 365738
@overnete
www.facebook.com/OverNetEducation
www.linkedin.com/company/overnet-solutionswww.wpc2015.it
www.wpc2015.it – info@wpc2015.it - +39 02 365738.11 - #wpc15it 41