Swagger to framework, który pozwala wizualizować i korzystać z aplikacji API, przy okazji tworząc dokumentację. Podstawowa konfiguracja Swaggera nie jest zbyt trudna, trwa zwykle nie więcej niż dwadzieścia minut. Swagger sprawia, że projektowanie interfejsu API jest znacznie prostsze.
Największym plusem wykorzystania tego narzędzia jest jednak uzyskanie samoaktualizującej się dokumentacji. Dzięki temu programiści nie muszą wraz z każdą zmianą dokonywać modyfikacji zapisanej dokumentacji. Jej utrzymanie jest trudne, często zawiera błędy wynikające z drobnych pomyłek programisty w jej tworzeniu lub rozbieżności pomiędzy wersją API a wersją dokumentacji. Na szczęście powstał Swagger, który ściąga z barków programistów ten problem.
Kiedy chcemy wygenerować dokumentację referencyjną, mamy do wyboru naprawdę szeroką gamę programów, które mogą to zrobić na podstawie definicji API. Najlepiej sprawdzają się narzędzia z pakietu Swaggera, za którego sprawą standard ten w ogóle powstał.
W pakiecie Swaggera jest kilka programów. Najczęściej wykorzystywane to:
Swagger Editor – program ten umożliwia pisanie specyfikacji OpenAPI bezpośrednio w przeglądarce. Wtedy w czasie rzeczywistym następuje weryfikacja, czy pisana definicja jest zgodna z odpowiednim standardem. Od razu generuje się też podgląd dokumentacji. Ułatwia to dostrzeżenie błędów merytorycznych, jeżeli takowe wystąpią.
Swagger UI – możemy z niego skorzystać, kiedy mamy już gotową definicję OpenAPI. Swagger UI wygeneruje na jej podstawie dokumentację referencyjną. Powstałą tym sposobem stronę internetową można umieścić na dowolnym serwerze, gdzie użytkownicy będą mogli z niej korzystać.
Ważnym elementem wiedzy o Open API jest specyfikacja. Specyfikacja ta polega na opisie API RESTful za pomocą pliku JSON/YAML – można jej użyć do tworzenia próbnego serwera, generowania dokumentacji przez użytkownika, generowania kodu i wielu innych rzeczy. Specyfikacja OAS jest niezależna od języka, w którym piszemy – jest rozumiana przez ludzi oraz komputery.
Standard API jest oparty na standardzie REST, wykorzystując jednocześnie format reprezentacji danych definiowany standard JSON-a. Zalecenia związane ze standardami dokumentacji API:
opis zasobów,
opis obsługiwanych metod i punktów dostępowych,
parametry obsługiwane przez punkt dostępowy,
przykłady kodu żądań, obrazujących użycie złożonych, ale nie skomplikowanych zapytań.
Podsumujmy, dlaczego Swagger jest narzędziem bardzo chętnie wykorzystywanym przez programistów przy tworzeniu dokumentacji API. Przede wszystkim ułatwia pracę w znaczący sposób – tworzenie dokumentacji, które przysparza sporo kłopotów, można dzięki Swaggerowi uprościć i zautomatyzować. Dzięki temu zapisanie endpointu ogranicza się do kilku linijek kodu. Program zapobiega również powstawaniu wielu błędów, które mogą wystąpić w momencie, gdy programista musi wraz z każdą zmianą dokonywać modyfikacji dokumentacji.
Nasi Programiści chętnie korzystają z tego systemu, ponieważ ich praca dzięki temu jest sprawniejsza, szybsza, a ich działania bardziej efektywne i obarczone mniejszym ryzykiem błędu. Dzięki prostym plikom takim jak JSON czy YAML mogą zwiększyć jakość swojej pracy.