Dal nuovo ASP.NET and Web Tools 2012.2, il template di progetto ASP.NET Web API si è dotato di una funzionalità estremamente comoda: stiamo parlando di help page, ossia della possibilità di generare, in maniera del tutto automatica, delle guide online sui servizi che esponiamo. Ciò avviene grazie a un HelpController, situato nell'area HelpPage del progetto.
![](https://www.aspitalia.com/script/images/1120.jpg)
HelpController si occupa di produrre una documentazione HTML grazie all'oggetto ApiExplorer; questa pagina di help sarà accessibile dal percorso /help (che possiamo comunque personalizzare ridefinendo la route) e offrirà un valido aiuto agli sviluppatori che intendono impiegare la nostra API nel loro progetto client.
Per ogni risorsa disponibile nel progetto ASP.NET Web API, questa guida elenca tutti i metodi di tipo GET, POST, PUT e DELETE per l'esecuzione di operazioni CRUD, visualizzando testi descrittivi per le action e i loro parametri, oltre che fornire codice JSON o XML di esempio da fornire come payload della richiesta.
![](https://www.aspitalia.com/script/images/1120_2.jpg)
Documentare la nostra Web Api è quasi immediato: ci si può avvalere della documentazione XML in tre semplici passi, il primo dei quali consiste nell'annotare la action come nell'esempio in basso.
/// <summary> /// Aggiorna un prodotto esistente /// </summary> /// <param name="id">L'ID univoco del prodotto</param> /// <param name="product">Il prodotto da aggiornare</param> public void PutProduct(int Id, Product product) { //Codice per l'aggiornamento }
A questo punto, dovremo assicurarci, dalle proprietà del progetto, che alla compilazione venga prodotto un file XML di documentazione, sfruttando l'opzione in figura.
![](https://www.aspitalia.com/script/images/1120_3.jpg)
L'ultimo passaggio consiste nell'impostare il percorso dell'XML di documentazione nella classe di configurazione del provider HelpPageConfig.
config.SetDocumentationProvider(new XmlDocumentationProvider( HttpContext.Current.Server.MapPath("~/App_data/DocumentazioneWebApi.xml")));
Il risultato di questa operazione sarà simile a quello mostrato in figura.
![](https://www.aspitalia.com/script/images/1120_4.jpg)
Commenti
Per inserire un commento, devi avere un account.
Fai il login e torna a questa pagina, oppure registrati alla nostra community.
Approfondimenti
Configurare policy CORS in Azure Container Apps
Evitare la script injection nelle GitHub Actions
Assegnare un valore di default a un parametro di una lambda in C#
Generare un hash con SHA-3 in .NET
Aggiungere interattività lato server in Blazor 8
Gestione degli stili CSS con le regole @layer
Utilizzare l'operatore GroupBy come ultima istruzione di una query LINQ in Entity Framework
Short-circuiting della Pipeline in ASP.NET Core
Supporto ai tipi DateOnly e TimeOnly in Entity Framework Core
Potenziare Azure AI Search con la ricerca vettoriale
Load test di ASP.NET Core con k6
Registrare servizi multipli tramite chiavi in ASP.NET Core 8
I più letti di oggi
- ecco tutte le novità pubblicate sui nostri siti questa settimana: https://aspit.co/wkly buon week-end!
- Windows Server 2003 SP1 Italiano
- Creare un modulo e un controller con AngularJS
- Build 2014: tutte le novità per gli sviluppatori in diretta da San Francisco
- Rilasciata la versione RTM di Windows Vista SP1