RESTful API con Swagger

Oggetto di questa nota sarà swagger, un set di strumenti e di specifiche Open Source che stanno diventando lo Standard de facto per quel che riguarda l’implementazione e la documentazione di un’API RESTful.

Per comprendere cosa swagger sia e quale utilità abbia nel processo di sviluppo di una API, esistono in rete molti articoli, tra i quali API con Swagger in 5 minuti, Swagger specification, e via dicendo.

Seguendo lo spirito del blog, invece, utilizzerò questo post per memorizzare una possibile serie di passi per introdurre l’utilizzo dello strumento in una Web API sviluppata con il framework ASP.NET Core.

A tal fine partiremo da uno dei progetti sviluppati a titolo di esempio nei post precedenti, e pubblicati su Azure.

Tra i possibili strumenti per l’integrazione di swagger nel nostro processo, ci serviremo di Swashbuckle.
In primo luogo, aggiungiamo al file project.json del nostro progetto, la dipendenza alla versione attuale di Swashbuckle.

...
"Swashbuckle": "6.0.0-beta901",
...

Quindi, configuriamo la nostra App affinché faccia uso dello strumento in questione, aggiungendo nel metodo ConfigureServices, le seguenti righe:

            // Inject an implementation of ISwaggerProvider with defaulted settings applied
            services.AddSwaggerGen();

            services.ConfigureSwaggerGen(options =>
            {
                options.SingleApiVersion(new Info
                {
                    Version = "v1",
                    Title = "BookStore API",
                    Description = "A sample API  for swagger usage demonstration",
                    TermsOfService = "None",
                    Contact = new Contact() { Name = "Maurizio Attanasi", Email = "", Url = "https://maurizioattanasi.blogspot.it/" },
                    License = new License() { Name = "Creative Commons Attribution 4.0", Url = "https://creativecommons.org/licenses/by/4.0/" }
                });

                //Determine base path for the application.
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;

                //Set the comments path for the swagger json and ui.
                var xmlPath = Path.Combine(basePath, "BookApi.xml");
                // options.IncludeXmlComments(xmlPath);
            });        

Infine, nel metodo Configure, subito dopo aver avviato il pattern MVC, configuriamo l’uso sia di Swagger che della sua interfaccia utente:

            app.UseMvc();

            // Enable middleware to serve generated Swagger as a JSON endpoint
            app.UseSwagger();

            // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.)
            app.UseSwaggerUi();

Avviata la web application, e navigando all’indirizzo your-root-url/swagger/ui, nel nostro caso http://talking-things-api.azurewebsites.net/swagger/ui/, visualizzeremo la pagina di documentazione autogenerata

 Degno di nota è anche il fatto che la pagina fornisce anche un client che consente di testare il servizio senza ricorrere a tool esterni quali Postman o Fiddler. Espandendo infatti uno dei verbi visualizzati nella pagina, ed agendo sul pulsante Try it out, abbiamo

Enjoy.

Integrazione Continua su Azure con git e azure-cli (parte II)

Continuiamo la precedente nota su Integrazione Continua su Azure con git e azure-cli, nella quale ho illustrato una possibile procedura per l’implementazione di un ambiente di sviluppo per l’integrazione continua su Microsoft Azure. In quell’occasione il progetto pubblicato implementava sia la gestione del front-end (sviluppato in quell’occasione con un’applicazione Angular 2), che il back-end (implementato con ASP.NET Core) implementata su host IIS.

In questo post concentreremo la nostra attenzione solo sulla pubblicazione di una Web App Angular 2 implementata con Node.js. A tal fine ci avvarremo di angular-cli, un set di strumenti in linea di comando per lo sviluppo di un'app Angular 2.

Creazione della Web App

Seguendo le istruzioni riportate dal sito creiamo una Web App Angular 2 con angular-cli.

1. In primo luogo installiamo sul nostro sistema angular-cli:

$ npm install -g angular-cli

2. Quindi creiamo la nostra Web App:

$ ng new my-a2-app

3. Personalizziamone il contenuto, modificando:
   
   • il file app.component.ts

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'my angular 2 app!';
  sign = 'Maurizio Attanasi';
  year = '2016';
}

• il file app.component.html
  
4. Avviamo il server in locale con il comando

$ ng serve


.
5. Aggiungiamo nella directory root del progetto il file .deployment che configurerà la directory di avvio del progetto, e contenente le righ che seguono:

[config]

project = dist

Preparazione e pubblicazione della Web App su azure

1. Utilizzando le funzionalità di azure-cli viste nel post precedente, creiamo la Web App

$ azure site create my-a2-app --git --gitusername ***

2. Aggiorniamo le modifiche del repository locale, eseguiamo il commit ed infine eseguiamo il push verso il repository remoto di azure

$ git add .

$ git commit -m "Initial commit"

$ git push azure master

Se la è andata a buon fine, la nostra shell di comando sarà simile a quella seguente

Ulteriore conferma dell’avvenuta pubblicazione possiamo averla navigando il portale di azure al percoso my-a2-app > Deployment options

Ed infine, raggiungendo l’indirizzo http://my-a2-app.azurewebsites.net/

Enjoy