Swagger – dokumentowanie REST API

Wprowadzenie

Od wielu lat usługi REST wypierają stare dobre usługi SOAP (a można już chyba nawet powiedzieć, że wyparły). Kiedy zaczynałem tworzyć usługi REST oraz z nich korzystać, miałem w pewnym sensie wrażenia, że robimy krok w tył. W SOAP mieliśmy WSDLa, który opisywał usługę. Dzięki niemu Visual Studio mogło wygenerować wszystkie klasy, które następnie używałem do komunikacji z usługą.

W przypadku usług RESTowych nie mamy czegoś takiego z pudełka. Więc bardzo często spędzamy długie godziny, aby dodać sporo kodu, który wcześniej był generowany. Oczywiście wszystko do czasu, aż trafimy na tytułową bibliotekę. W tym wpisie pokaże Ci w jaki sposób dodać do WebApi dokumentacje usługi z wykorzystaniem Swaggera. Szczególnie, że wiele osób nie wie jeszcze o istnieniu tego narzędzia.

WebApi

Aby zobaczyć, jak działa Swagger przygotowałem proste WebApi, które posłuży nam do testów. Tradycyjnie przykład znajduje się na githubie (https://github.com/danielplawgo/SwaggerExample). Api jest dość proste. Udostępnia jeden kontroler, który umożliwia zarządzanie produktami w aplikacji.

Klasa Product wygląda tak:

Natomiast testowy kontroler tak:

Jak widać nie ma tutaj nic bardzo skomplikowanego. Klasa Product zawiera kilka prostych właściwości. Natomiast kontroler udostępnia metody, które modyfikują dane zapisane w lokalnej statycznej liście. Na start dane są generowane z wykorzystaniem biblioteki Bogus.

Zwróć uwagę, że kod zawiera komentarze dokumentujące poszczególne elementy kodu. Jest to o tyle pomocne, że później Swagger wykorzysta je podczas generowania dokumentacji. Komentarze te można wygenerować za pomocą dodatku GhostDoc, który omawiam w moim darmowym kursie Visual Studio.

Domyślnie niestety nie mamy żadnego narzędzia, które udokumentowało by nam nasze api oraz później pomogło w wygenerowaniu proxy do wywołaniu usługi.

Swagger

Swagger to nie tylko biblioteka do generowania dokumentacji tworzonego api. To przede wszystkich cały ekosystem narzędzi, które umożliwiają nam tworzenie RESTowego api. Ekosystem zawiera narzędzia do projektowania api, jego dokumentowania, czy też testowania. Otrzymujemy dziesiątki narzędzi, które wspierają różne języki programowania, technologie, frameworki. Więcej informacji o całym ekosystemie znajdziesz na stronie głównej Swaggera – https://swagger.io/.

Z czasem na blogu będą pojawiały się opisy kolejnych elementów ekosystemu, które możesz wykorzystać do tworzenia lepszego REST api.

Dokumentowanie WebApi

Dodanie dokumentowania WebApi za pomocą Swagger jest bardzo proste. Wystarczy w pierwszej kolejności dodać pakiet Swashbuckle z nugeta. Pakiet po zainstalowaniu doda do projektu nowy plik o nazwie SwaggerConfig, który znajduje się w katalogu App_Start. Klasa znajdująca się w pliku jest odpowiedzialna za konfigurację Swaggera i jest wywoływana podczas startu aplikacji.

W klasie możemy skonfigurować dwie rzeczy: sposób generowania dokumentacji api przez Swaggera oraz Swagger UI (o tym w kolejnej sekcji artykułu). Przykładowa zawartość SwaggerConfig może wyglądać tak (usunąłem zbędne komentarze):

Atrybut przed namespacem informuje, że metoda Register z tej klasy zostanie wykonana podczas startu aplikacji. W metodzie jak wspomniałem konfigurujemy dwie rzeczy:

  • EnableSwagger – uruchamia generowanie dokumentacji, w przekazanym delegacie możemy to skonfigurować np. IncludeXmlComments określa, że komentarze dokumentujące z kodu mają być wykorzystane do opisów w dokumentacji
  • EnableSwaggerUi – uruchamia oraz konfiguruje SwaggerUI

W wygenerowanej klasie znajduje się sporo komentarzy pokazujących jak skonfigurować różne aspekty biblioteki. W przykładzie je usunąłem, ale planuje w przyszłości dodać więcej wpisów na temat Swagger, w których pokaże Ci inne funkcje biblioteki oraz całego ekosystemu.

Darmowy kurs Visual Studio

Pracując z setkami programistów zauważyłem, że większość osób nie pracuje efektywnie w Visual Studio. W skrajnych przypadkach korzystali z kopiowania z wykorzystaniem menu Edit. Wiem, że to dziwne, ale naprawdę niektórzy tak pracują. Dlatego postanowiłem stworzyć kurs Visual Studio, aby pomóc koleżankom i kolegom w efektywniejszej pracy.

Przygotowałem 20 lekcji email, w których pokaże Ci w jaki sposób pracować efektywnej i szybciej w Visual Studio. Poznasz dodatkich, bez których nie wyobrażam sobie pracy w tym IDE.

Po więcej informacji zapraszam na dedykowaną stronę kursu: Darmowy Kurs Visual Studio.

Quiz C#

Ostatnio przygotowałem również quiz C#, w którym możesz sprawdzić swoją wiedzę. Podejmiesz wyzwanie?

SwaggerUI

SwaggerUI jest prostym interfejsem użytkownika, za pomocą którego możemy przejrzeć dostępne api wraz z opisem oraz przetestować te api.

Po uruchomieniu aplikacji SwaggerUI jest dostępny pod adresem [adres aplikacji]/swagger/ui/index i w testowym projekcie wygląda tak:

swagger ui

Jak widać na zrzucie ekranu powyżej, SwaggerUI wyświetla informacje o wszystkich dostępnych kontrolerach oraz akcje, które udostępnia. Widzimy jakie są typu żądań oraz z prawej strony widać komentarze, które są ustawione w kodzie przy poszczególnych akcjach.

Testowanie

SwaggerUI poza wyświetleniem informacji o api daje również możliwość jego przetestowania. Wystarczy kliknąć na adres wybranej akcji. Wtedy rozwinie się panel, w którym możemy z jednej strony uzyskać więcej informacji o akcji. Z drugiej strony możemy ją wywołać i zobaczyć wynik. Co widać na zrzucie ekranu poniżej, gdzie jest wywołana akcja dla typu żądania Get, w której przekazujemy id produktu, którego dane chcemy zobaczyć:

swagger ui invoke action

W sekcji Parameters wpisujemy Id produktu (na zrzucie 1) i następnie naciskamy przycisk „Try it out!” (zaznaczony czerwoną ramką). Po chwili niżej zobaczymy odpowiedź z api, w tym przypadku dane testowego produktu.

W podobny sposób możemy przetestować pozostałe akcje, które udostępnia api.

Przykład

Na githubie (https://github.com/danielplawgo/SwaggerExample) dostępny jest testowy projekt, który użyłem do przygotowania tego wpisu. Możesz go pobrać i uruchomić. Nie jest potrzebna jakaś dodatkowa konfiguracja. Testowy ProductsController przy starcie generuje za pomocą biblioteki Bogus 10 produktów, które mogą posłużyć Ci do testowania api.

Zachęcam do pobrania przykładu i pobawienia się SwaggerUI.

Podsumowanie

Swagger jest biblioteką, bez której dzisiaj nie wyobrażam sobie tworzenie WebApi. Jedną z pierwszych rzeczy, którą robię po utworzeniu aplikacji jest dodanie tej biblioteki. Dzięki temu praktycznie bez wysiłku mam prosty interfejs, który udostępnia mi informacje o api oraz umożliwia testowanie go.

Ale Swagger to nie tylko dokumentowanie api. W jednym w kolejnych wpisów pokaże Ci w jaki sposób można wykorzystać dane udostępnione przez Swaggera do generowania klienta naszego api. Co fajne, są dostępne narzędzia praktycznie do każdego dostępnego języka i środowiska. Na co dzień wykorzystuje to podczas tworzenia klienta w .NET oraz Angularze. Ale to już temat na zupełnie inny wpis.

1 thought on “Swagger – dokumentowanie REST API

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *