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.