top of page
  • Zdjęcie autoraKarol Pietruszka

Dokumentacja API z użyciem Swaggera


Webchefs_Software _for_humans_API_documentation_with_Swagger_article

API to skrót od angielskiej nazwy application programming interface, co oznacza po prostu interfejs programowania aplikacji. Jest to zbiór reguł, które ściśle opisują w jaki sposób programy lub podprogramy komunikują się ze sobą.


Obowiązek dokumentowania API najczęściej przypada osobom piszącym kod, dzieje się tak przez wzgląd na specyficzny, wysoce techniczny charakter tego zadania, a także ze względu na docelowych użytkowników dokumentacji. Chodzi tutaj przede wszystkim  o programistów. Same narzędzia używane do tworzenia dokumentacji API wymagają sporej wiedzy technicznej, specjalistycznej, ale także doświadczenia praktycznego od osób, które się nimi posługują.



Czym jest Swagger?


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.



Rodzaje Swaggera


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ń.




Dlaczego warto korzystać ze Swaggera przy tworzeniu API?


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. 

2 wyświetlenia0 komentarzy

Ostatnie posty

Zobacz wszystkie

Bình luận


bottom of page