Artykuł

freeimages.com freeimages.com
maj 26 2016
0

Swashbuckle - bardzo dobra dokumentacja dla Web API

Wiecie jaki problem jest z dokumentacją? Wszyscy chcieliby ją mieć, ale mało osób lubi ją tworzyć. Ten problem nie omija również deweloperów, którzy pisanie dokumentacji (obojętnie czy to w postaci do kodu, czy niezależnych dokumentów) traktują jako swego rodzaju karę.

Na szczęście są obszary IT, gdzie dokumentacja może się generować sama.. No dobra prawie sama, ale w pewnym sensie jej tworzenie możemy oprogramować. Takim obszarem jest np. popularne Web API, które posiada kilka rozwiązań softwarowych, pozwalających na generowanie dokumentacji.

Jakiś czas temu poszukiwałem optymalnego rozwiązania, które będzie w stanie dać konsumentom API maksimum informacji i wszystko na to wskazuje, że znalazłem to jedyne. Moi mili - chciałbym Wam przedstawić Swashbuckle, czyli implementację popularnego Swaggera przystosowaną do naszego ulubionego Web API:-)

Czym jest Swagger i Swashbuckle?

Swagger to bardzo popularny (według autorów najpopularniejszy na świecie) framework wspomagający tworzenie restowego API. Bazowa biblioteka napisana została w Javie, ale istnieją również wersje dedykowane dla innych technologii.

Dla C# mamy mamy Swashbuckle, którego kod można znaleźć na GitHubie. W przypadku .Neta to rozwiązanie używane jest przede wszystkim jako mechanizm generujący dokumentację do API.

Swashbuckle jest stosunkowo prosty w użyciu i w podstawowej formie nie wymaga jakiejś przesadnej konfiguracji, aczkolwiek jeśli tylko chcemy, to możemy z nim zdziałać dosłownie cuda;-)

Instalacja

Swashbuckle dostępny jest na Nugecie i w chwili obecnej istnieją dwie główne paczki. Jeśli Wasz projekt jest hostowany na IIS, to powinniście w Package manager console wydać następującą komendę:

Install-Package Swashbuckle

W przypadku gdy preferujecie rozwiązanie self-hosted, lub OWINa, powinniście skorzystać z polecenia:

Install-Package Swashbuckle.Core

W kolejnym kroku należy przeprowadzić bazową konfigurację, której szczegóły możecie poznać na stronie projektu pod nagłówkiem Getting started.

Opisywanie kodu

Swashbuckle wykorzystuje komentarze (wynikowe pliki XML należy aktywować dla danego assembly), data annotations oraz zestaw specjalnych atrybutów do opisywania kodu Web API. Dzięki temu możemy m.in. określić:

  • Jaki obiekt zwraca nam dane żądanie przy jakim kodzie odpowiedzi HTTP
  • Z jakim rodzajem metody mamy do czynienia
  • Jakie parametry musimy użyć i które z nich są wymagane?
  • Opisać komentarzem co dokładnie robi dana metoda, co robią poszczególne pola argumentów oraz odpowiedzi

Jak widać możliwości jest sporo i warto przyjrzeć się wszystkim dostępnym funkcjom opisanym w dokumentacji projektu.

Poniżej przykładowy kod opisujący metodę API:

/// <summary>
/// Adds new dentist office
/// </summary>
/// <param name="dentistOffice">Dentist office</param>
/// <returns>IHttpActionResult</returns>
[HttpPost]
[Route("Add")]
[SwaggerResponse(System.Net.HttpStatusCode.OK)]
[SwaggerResponse(System.Net.HttpStatusCode.BadRequest, Type = typeof(ResponseInvalidModelState))]
[SwaggerResponse(System.Net.HttpStatusCode.Unauthorized, Type = typeof(ResponseMessage))]
[SwaggerResponse(System.Net.HttpStatusCode.NotFound, Type = typeof(ResponseMessage))]
[SwaggerResponse(System.Net.HttpStatusCode.InternalServerError, Type = typeof(ResponseException))]
public IHttpActionResult Add(Contracts.DTO.DentistOffice dentistOffice)
{
    // Some action

    return Ok();
}

Dodatkowe możliwości

Na koniec chciałbym jeszcze wspomnieć o ważnej rzeczy, o której nie napisałem wcześniej - Swashbuckle pozwala na uruchomienie dowolnej metody z naszego API z poziomu swojej strony dokumentacji! Po uruchomieniu WWW, wystarczy wybrać wskazaną metodę, dodać parametry (domyślny zestaw parametrów możemy łatwo przekopiować), a następnie kliknąć na przycisk wywołania.

W sytuacji gdy nasze API operuje na tokenach OAuth, to wciąż istnieje możliwość testowania kodu, ponieważ logowanie możemy dopisać w JavaScript. Swashbuckle umożliwia wpięcie własnego kodu JS oraz CSS za pomocą konfiguracji i to niewątpliwie kolejny, istotny ficzer tego rozwiązania.

Podoba Ci się ten wpis? Powiedz o tym innym!

Send to Kindle

Komentarze

blog comments powered by Disqus