Lucian Maran

home

ASP.NET Web Api - Generarea automata a documentatiei (Help Page)

13 Sep 2012

Este vorba de o facilitate care genereaza documentatia automat pentru resursele REST API, pe baza comentariilor cu care este "ornamentat" codul.

Exemplu de cod:

...si documentatia generata:

Cum se face asta?

Recomand intai parcurgerea acestui video tutorial. Pe scurt, pasii sunt urmatorii:

  1. Din Visual Studio, instalezi ASP.NET Web Api Help Page

  2. Configurezi proiectul sa genereze documentatia intr-un fisier XML:

Astfel, fisierul cu documentatia in format .xml se genereaza automat, la fiecare compilare.

Observatie: Odata facuta aceasta activare, compilatorul genereaza un Warning pentru fiecare clasa sau metoda publica care nu este comentata corespunzator. Avertismentul ar fi util daca s-ar aplica doar la codul propriu, dar se aplica si la toate clasele incluse in bibliotecile externe la care faci referire. La mine, de exemplu, dupa ce am activat generarea automata a documentatiei s-au generat cateva sute de warning-uri, fiindu-mi greu astfel sa decelez intre alertele “utile” si cele de tip "lipsa comment":

O solutie ar fi folosirea directivei #pragma warning in interiorul fiecarei clase. Dezavantaje: - volumul mare de munca - nu poti face acest lucru in clasele aflate in biblioteci externe

O alta solutie (asta am folosit eu) ar fi adaugarea valorii 1591 in sectiunea "Supress warning", ca in figura prezentata putin mai sus. In acest fel, sunt filtrate erorile de tip "lipsa comentariu" si raman doar atentionarile utile:

  1. Actualizeaza in Areas/HelpPage/App_Start/HelpPageConfig.cs adresa fisierului ce contine documentatia .xml:

  1. Optional, modifica layout-ul paginii de help a.i. sa fie in concordanta cu layout-ul intregii aplicatii MVC:

  1. Optional, poti decora un anumit controller sau doar o metoda cu atributul [ApiExplorerSetting(IgnoreApi=true)] a.i. acestea sa fie excluse din procesul de generare a documentatiei. Sau poti face acest lucru prin cod, asa cum este prezentat aici.

  2. Modulul "HelpPage" determina automat denumirea si tipul proprietatilor pentru un anumit tip de date, si le initiaza cu niste valori predefinite:

Daca doresti, poti folosi fisierul HelpPageConfig.cs pt. a-ti define propriile exemple (valori) pt. un anumit tip, astfel:

Rezultat:

Unele actiuni pot returna HttpResponseMessage in loc de un tip explicit definit. Pagina de Help nu recunoaste acest tip si, in acest caz, nu afiseaza nimic in sectiunea de "Response". Solutia consta tot intr-o modificare in fisierul HelpPageConfig.cs:

Astfel, pentru o metoda API care returneaza un HttpResponseMessage ca mai jos:

...se va genera o documentatie a carei sectiune de tip "Response" va arata astfel:

...unde tipul "CrmInvoiceDetail" putea fi si el customizat dupe metoda prezentata mai sus, la "Counter".

comments powered by Disqus