Jakub Raczkowski 
Jak pochwalić się backendem? Z frontem sprawa jest jasna: wrzucamy projekt na serwer i udostępniamy adres www prowadzący np. do index.html gdzie dzieje się cała magia. A co z API? Swagger (Open API 3.0) ma na to odpowiedź.
Uwaga! W tej serii zajmuję się opisowym przedstawieniem tematu, a celem jest zapoznanie z zagadnieniem w sposób luźny i zrozumiały dla nowicjusza. W związku z tym wiele elementów siłą rzeczy musi zostać pominiętych. Tych z was, którzy chcieliby się dowiedzieć więcej, zapraszam do źródeł na końcu artykułu.
Wyobraźcie sobie, że tworzycie backend do jakiegoś programu.
GUI albo nie ma wcale, albo jest takie, że już chyba lepiej jakby go nie było. Z resztą… c**j z nim, nieważne, liczy się żeby logika działała z sensem, a SQL-ki były dobrze zoptymalizowane.
To w końcu backend.
No i jest! W końcu! Sukces, udało się! Program robi co ma robić, testy przechodzą, wszystkie wyjątki wyłapane i obsłużone. Appka zapakowana w elegancki kontener i wywalona na serwer. Koniec?
API to inaczej: „interfejs dostępu do aplikacji”. Jeśli jest stworzony w popularnym standardzie REST to sprowadza się do wystawienia endpointów i ustawienia metod HTTP jakie one obsługują.
Dla przykładu powiedzmy, że zrobiliśmy aplikację do odsłuchiwania utworów muzycznych. Mamy bazę danych z piosenkami i aplikację która daje do nich dostęp, np. pod adresem www.moja.muza – jak tylko tam wejdziemy zacznie się odtwarzać losowy kawałek. To mogłoby wystarczyć, ale lepiej jak damy użytkownikowi jakąś kontrolę nad naszym playerem i wystawimy w tym celu dedykowane endpointy:
– www.moja.muza/pause -> pauzuje odtwarzany utwór (HTTP GET)
– www.moja.muza/play -> wznawia odtwarzany utwór (HTTP GET)
– www.moja.muza/{rating} -> nasza osobista ocena lecącej piosenki (HTTP GET)
– www.moja.muza/remove/{track_id} -> możliwość szybkiego usunięcia danego utworu z bazy (HTTP DELETE)
API gotowe, teraz można zabrać się za front i sprawić żeby to jakoś wyglądało. Tu, rzecz jasna, pojawia się zgrzyt, bo przecież siedzisz w backendzie i nie znasz się na HTML, CSS i JS.
Prosisz o pomoc kolegę. Ten się zgadza i chce dokumentację twojego API. Wysyłasz mu w komunikatorze pokazane powyżej endpointy (trochę wieje amatorszczyzną, ale przecież nie ma tego dużo więc po co kombinować?) i zaczyna się budowa strony wejściowej.
A ty tymczasem czekasz, nudzisz się, patrzysz na swój kod i do głowy przychodzą ci nowe pomysły…
- Pause? Play? Po co aż tak? Przecież jeden endpoint może obsłużyć obie te komendy: jak gra to pauzuje, a jak nie gra to włącza.
- Rating? Hmm, a może zamiast suchej oceny dodać komentarz? No ale wtedy trzeba by tekst wysłać JSON-em i lepiej zmienić metodę na POST.
- Zaraz, ale nie chcę żeby każdy mógł wywalać piosenki z mojej bazy! Tylko admin, czyli ja!
Modyfikujesz więc swój kod i wysyłasz poprawioną wersję do kolegi. Ten trochę marudzi, ale koniec końców bierze się za zmiany.
A ty tymczasem czekasz, nudzisz się, patrzysz na swój kod i do głowy przychodzą ci nowe pomysły…
- A co jeśli komuś nie podejdzie ta piosenka? Przydałaby się możliwość przeskoczenia do następnej w kolejce.
- Albo przeciwnie – utwór tak wszedł, że użytkownik chce go usłyszeć jeszcze raz!
- A może w ogóle zrobimy osobistą listę ulubionych, wtedy jeden endpoint pobiera listę, a inny dodaje/usuwa z niej utwory.
Modyfikujesz więc swoje API i wysyłasz poprawioną wersję do kolegi. Ten już powoli traci cierpliwość, ale zagryza wargi i leci z tematem.
A ty tymczasem czekasz, nudzisz się, patrzysz na swój kod i do głowy przychodzą ci nowe pomysły…
Mam nadzieję, że już widzicie problem który staram się nakreślić:
Program z czasem ewoluuje
i to samo powinna robić jego dokumentacja.
Owszem, możemy dokumentować API samodzielnie w edytorze tekstu. Ba! Możemy po prostu wrzucić kod do Chata GPT i jego poprosić o wygenerowanie dokumentacji! Chwila moment i gotowe!
Ale to i tak nic
w porównaniu z tym
co oferuje Swagger.
Jeśli chciałbym opisać jednym zdaniem czym jest Swagger (znany również pod nazwą OpenAPI) to jest to dodatek do projektu – wrzucany jako kolejna zależność w Mavenie/Gradle, który zajmuje się dynamicznym tworzeniem dokumentacji wystawionych endpointów.
W Swaggerze znajdziemy wszystkie endpointy (pogrupowane wg kontrolerów), info na temat metod HTTP jakie się za nimi znajdują, szablony obiektów JSON jakie możemy wysłać, nagłówki, zwracane kody, możliwe wyjątki, opisy…
Swagger pozwoli też na wypróbowanie każdego endpointa przez co świetnie sprawdza się jako narzędzie do szybkiego testowania API – do podstawowych zastosowań nie musimy nawet uruchamiać Postmana!
Gaminatorium
Swagger jest nieodłącznym elementem API Gaminatorium dzięki któremu informujemy frontend o tym co zostało już zrobione i z jakich endpointów mogą korzystać testując własny kod.
Uwielbiam prostotę jaką charakteryzuje się OpenAPI, wystarczy, że dodam poniższą zależność do Gradle i gotowe*!
implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.5.0'(*) Prawie, bo trzeba jeszcze napisać krótką klasę konfiguracyjną dodającą opowiedniego Bean’a do Springa
Teraz za pomocą prostej adnotacji mogę samodzielnie dodać opis endpointa, który pokaże się w GUI Swaggera, natomiast cała reszta zostanie wygenerowana w pełni automatycznie!
Swagger jest trochę jak Lombok (o nim też będzie stosowny tekst) – na początku zastanawiamy się: „po co nam to?”. Po co dodawać kolejne zależności i komplikować strutkurę projektu? Ale kiedy już raz spróbujemy tej wygody to ciężko będzie kiedykolwiek wrócić do starych metod.
Podsumowując, Swagger jest świetny, bo:
– dodanie go do projektu to chwila-moment
– sam dokumentuje API i robi to kompleksowo, ogarnia wszystkie niezbędne rzeczy
– owa dokumentacja zmienia się dynamicznie, razem z kodem – kolejna rzecz o której już nie musimy pamiętać
– oferuje proste, ale czytelne GUI gdzie znajdziemy wszelkie niezbędne informacje i sami sprawdzimy czy wszystko działa
Źródła:
– Kanał Przemka Bykowskiego YT/POL
– Swagger.io – official page
