Swagger-Net - Documentazione dinamica

Con il Framework 4.8 , in un un contesto di WebApi, Swagger interviene generando una documentazione interattiva HTML che prende come sorgente i modelli dei dati e le loro descrizioni da codice sorgente.

Pagina del progetto: https://github.com/heldersepu/Swagger-Net

Ecco come procedere, avendo già creato un WebApi/Rest-Service:

• Manage NuGet packages e installare Swagger-Net
• È possibile testare subito runnando la soluzione alla pagina /swagger (se non funziona qui sono cazzi tuoi)
• Si crea in automatico un file App_Start/SwaggerConfig.cs , centralizzato, dal quale è possibile configurare tutto.

Route personalizzata

Siccome runnare su /swagger ci fa schifo, cambiamo l'impostazione della route aggiungendo il parametro routeTemplate alla configurazione di Swagger SwaggerUI

GlobalConfiguration.Configuration.EnableSwagger("docs/{apiVersion}", c => { c.SingleApiVersion("v1", "Designbest REST-API"); /* ... */ })
GlobalConfiguration.Configuration.EnableSwaggerUi("doc/{*assetPath}", c => { c.DocumentTitle("Designbest REST-API"); /* ... */ })

In questo modo runniamo su /doc/index (ricordiamoci /index!).

Iniettare CSS e JavaScript

Per personalizzare i colori dell'interfaccia della documentazione è possibile inserire un proprio CSS custom.

• Creare un file CSS in un percorso dell'applicazione, es /Content/css/swagger-custom.css
• Cliccare sulle proprietà e nella Build Action impostare Embedded Resource (e Copy to Output directory mettere Copy always)
• A questo punto il nome logico della risorsa sarà App_Namespace.Folder.File, ad es DB_RestService.Content.css.swagger-custom.css
• Dalle impostazioni della SwaggerUI usare il comando:

c.InjectStylesheet(thisAssembly, "DB_RestService.Content.css.swagger-custom.css");

Stessa solfa per il javascript. Perché dovrei mettere del javascript in una documentazione? Per esempio per personalizzare la favicon che da CSS non può essere alterata:

(function () {
  var link = document.querySelector("link[rel*='icon']") || document.createElement('link');
  document.head.removeChild(link);
  link = document.querySelector("link[rel*='icon']") || document.createElement("link");
  link.type = "image/x-icon";
  link.rel = "shortcut icon";
  link.href = "https://www.designbest.com/favicon.png";
  document.getElementsByTagName("head")[0].appendChild(link);
})();