In un precedente script (https://www.aspitalia.com/script/1205/Documentare-ASP.NET-Web-API-Swagger.aspx) abbiamo visto come documentare il nostro progetto ASP.NET Web API 2 in accordo con la specifica Swagger.

Quest'oggi esamineremo la questione dal punto di vista di uno sviluppatore che voglia consumare la REST API dal proprio client .NET, sia esso un'applicazione ASP.NET o Windows.
Aggiungere un riferimento alla REST API è molto semplice poiché Visual Studio 2015 è in grado di generare le classi del modello per noi, in base al file di metadati JSON di Swagger 2.0.

Iniziamo facendo tasto destro sul progetto client e selezionando le voci Aggiungi e Azure API App Client.

Come si intuisce dal nome, la procedura è stata ottimizzata per le REST API distribuite con il servizio API App di Microsoft Azure ma è anche possibile selezionare il file di metadati JSON dal nostro disco fisso, dopo averlo ottenuto manualmente dalla pagina della documentazione.

La procedura genererà delle classi di modello coerenti con le risorse descritte dal file di metadati JSON. Verrà anche generata una ulteriore classe proxy dallo stesso nome della REST API, che useremo come punto di accesso principale. Grazie ad essa, ogni operazione GET, POST, PUT e DELETE sarà invocabile, a nostra scelta, sia mediante metodi sincroni che asincroni.

Al momento, la procedura di creazione del modello non viene offerta per progetti destinati al .NET Framework 4.0. E' comunque possibile compiere questa operazione usando direttamente il tool da riga di comando denominato AutoRest, di cui anche Visual Studio 2015 si avvale. Possiamo ottenere tale strumento da NuGet, digitando quanto segue dalla Console di gestione pacchetti:

Install-Package AutoRest

Troveremo l'eseguibile AutoRest.exe nella sottodirectory packages\autorest.0.12.0\tools della soluzione. Apriamo il prompt dei comandi, posizioniamoci in tale cartella e digitiamo ad esempio:

AutoRest.exe -Input C:\percorso\movieapi-v1.json 
  -OutputDirectory C:\percorso\client 
  -Namespace MyNamespace -CodeGenerator CSharp

I file di codice verranno creati nella directory di output indicata, così che possano essere inclusi ed utilizzati in un progetto, previa installazione del pacchetto Microsoft.Rest.ClientRuntime.

AutoRest è uno strumento cross-platform che può essere compilato ed usato anche su Mac OSX e Linux. Inoltre, è stato progettato per essere estendibile: grazie ai suoi code generators può infatti creare modelli per client .NET o per NodeJS e Ruby (ed eventuali altri linguaggi che verranno supportati in futuro).

La documentazione è disponibile nel repository GitHub del progetto.
https://github.com/Azure/autorest/tree/master/Documentation