Quando vengono create delle Web Api, spesso si ha la necessità di far interagire altri sviluppatori. E’ buona norma fornire la documentazione di tutte le API sviluppate ed il modo con il quale comunicare con le stesse. Il framework .NET consente di genereare facilmente la documentazione del nostro codice abilitando la possibilità di generare file in formato XML. Questi file possono essere utilizzati da programmi specifici, come ad esempio il progetto SandCastle che consente di creare la documentazione in formati differenti (ad esempio nel formato chm).

Per quanto riguarda le WebAPI esiste una libreria specifica che consente la generazione automatica della documentazione. Il progetto in questione si chiama WebApi.HelpPage e può essere facilmente installato nella nostra soluzione scaricandolo da nuget, il tool presente in Visual Studio. Non è necessario installare il pacchetto se la soluzione realizzata è di tipo “WebAPI”. Nel caso di integrazione WebApi con altre tipologie di soluzione è possibile installarlo eseguendo i seguenti passi:

  • dal menu Strumenti di Visual Studio selezionare Gestione Pacchetti Nuget -> Console di Gestione pacchetti
  • Nella console digitare il comando : Install-Package Microsoft.AspNet.WebApi.HelpPage. Nel caso in cui la soluzione sia di tipo Visual Basic è necessario utilizzare il comando Install-Package Microsoft.AspNet.WebApi.HelpPage.VB. Attenzione perchè esistono due tipologie differenti di librerie: una specifica per il linguaggio C# ed una per Visual Basic .NET .
  • Al termine dell’installazione verificare se all’interno della cartella Areas della nostra soluzione è stata creata una cartella HelpPage che conterrà tutto il contenuto per la visualizzazione della documentazione.
  • Modificare il contenuto del file Areas/HelpPage/App_Start/HelpPageConfig.cs togliendo il commento dalla riga:

    in questo modo il file della documentazione delle nostre WebApi sarà  XmlDocument.xml.
  • Abilitare la generazione automatica dei commenti in formato XML in fase di Compilazione della soluzione. Per fare questo è necessario cliccare nelle proprietà del progetto, nel menu Compila abilitare la generazione del file xml per la documentazione.

WebApi

Commentare il codice utilizzando i commenti con la modalità tradizione di Visual Studio, come nell’esempio:

A questo punto, la nostra soluzione è pronta. Per accedere da una View alla documentazione che verrà generata automaticamente si potrà utilizzare un ActionLink del tipo:

Se il progetto dovrà essere pubblicato in un ambiente di produzione, è necessario ricordarsi di includere al progetto il file App_Data/XmlDocument.xml in modo da renderlo disponibile online.

https://dotnettortona.net/wp-content/uploads/2015/09/LinkClick.aspx_.pnghttps://dotnettortona.net/wp-content/uploads/2015/09/LinkClick.aspx_-150x150.pngDotNetMicrosoft MVCMVC,REST,WebApiQuando vengono create delle Web Api, spesso si ha la necessità di far interagire altri sviluppatori. E' buona norma fornire la documentazione di tutte le API sviluppate ed il modo con il quale comunicare con le stesse. Il framework .NET consente di genereare facilmente la documentazione del nostro codice...La prima Community su .NET a Tortona (AL)