Jakiś czas temu, pisałem o Swagger, jako sposobie na dokumentacje REST API. Dzisiaj chciałbym pokazać kolejny mechanizm na generowanie dokumentacji, tym razem napisany przez Microsoft i dostępny od razu w ASP.NET. Od kilku lat jest on już dostępny bez żadnych dodatkowych instalacji.

Jeśli uruchomimy przykładową aplikację WebAPI, zobaczymy w prawym górnym rogu link do API:

Po kliknięciu w link API, zobaczymy wygenerowaną dokumentację:

Analogicznie do Swagger, możemy kliknąć na danej operacji i zobaczyć szczegóły:

UI możemy modyfikować. Jeśli przełączymy się do solucji, to zobaczymy, że całość jest umieszczona w Areas:

Najlepsze w tej dokumentacji jest to, że jest generowana na podstawie komentarzy. Nie musimy zatem edytować żadnych zewnętrznych plików JSON a dokumentacja sama jest bardzo blisko kodu (w formie komentarzy).

Przejdźmy zatem do kontrolera i dodajmy jakiś komentarz:

// GET api/Account/ManageInfo?returnUrl=%2F&generateState=true
/// <summary>
/// Przykladowy komentarz
/// </summary>
/// <param name="returnUrl">Parameter 1 blabla</param>
/// <param name="generateState">Paramter 2 blablabla</param>
/// <returns></returns>
[Route("ManageInfo")]
public async Task<ManageInfoViewModel> GetManageInfo(string returnUrl, bool generateState = false)

Jeśli skompilujemy teraz kod i przejdziemy do dokumentacji niestety nic nie zobaczymy. Domyślnie nie są analizowane komentarze XML. Musimy przejść do pliku HelpPageConfig i odkomentować następującą linie kodu:

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Następnie otwieramy właściwości projektu i w zakładce Build włączamy generowanie komentarzy XML do App_Data/XmlDocument.xml:

Po odpaleniu strony zobaczymy komentarze:

Jeśli kogoś interesuje jak działa powyższy mechanizm generowania dokumentacji zachęcam do poczytania o klasie ApiExplorer.

W każdym razie, dzięki temu mechanizmowi (ASP.NET HelpPages) nie rozsynchronizujemy pliku dokumentacji jak to możliwe było w przypadku Swagger.

Do Swagger jeszcze chcę powrócić w przyszłym poście, ponieważ istnieje wsparcie dla ASP.NET WebAPI i również większość rzeczy może być automatycznie generowane.