Dokumentacja API — Swagger, OpenAPI, Postman
Dokumentacja API bywa traktowana jako czynność porządkowa wykonywana na końcu projektu. W rzeczywistości to element, od którego zależy koszt każdej kolejnej integracji — a przy systemach otwieranych na partnerów decyduje o tym, czy integracja w ogóle dojdzie do skutku. Ten poradnik pokazuje, co powinna zawierać, kto ma ją utrzymywać i jak zapisać to w umowie.
Krótka odpowiedź: standardem jest OpenAPI — maszynowy opis interfejsu, z którego automatycznie powstaje czytelna dokumentacja i klienci w różnych językach. Dokumentacja powinna powstawać razem z kodem, a nie po jego napisaniu.
Trzy elementy odróżniają dokumentację użyteczną od formalnej: przykłady rzeczywistych żądań i odpowiedzi, kompletna lista kodów błędów oraz środowisko testowe, w którym integrator może sprawdzić działanie bez kontaktu z Twoim zespołem.
Po co w ogóle dokumentować interfejs
Argument techniczny jest oczywisty, ale to argument kosztowy przekonuje osoby decyzyjne. Integracja z dobrze udokumentowanym interfejsem zajmuje programiście od jednego do trzech dni. Ta sama integracja z systemem bez dokumentacji, gdzie trzeba dopytywać o każdy szczegół i domyślać się formatów, potrafi zająć dwa tygodnie — z czego znaczna część to czas Twojego zespołu spędzony na odpowiadaniu na pytania.
Ten rachunek mnoży się przez liczbę integracji. Jeżeli system podłączają partnerzy handlowi, każdy z nich przechodzi tę samą drogę osobno. Dokumentacja jest więc inwestycją, która zwraca się przy trzecim, czwartym podłączeniu — a w produktach otwartych na integracje przy pierwszym.
OpenAPI, Swagger, Postman — co jest czym
| Narzędzie | Czym jest | Do czego służy |
|---|---|---|
| OpenAPI | Standard opisu interfejsu w pliku tekstowym | Jedno źródło prawdy o strukturze interfejsu |
| Swagger UI | Strona generowana z pliku OpenAPI | Przeglądanie i testowanie zapytań w przeglądarce |
| Postman | Program do wysyłania zapytań | Gotowe kolekcje do przekazania integratorowi |
| Generatory klientów | Narzędzia czytające OpenAPI | Automatyczne biblioteki dla różnych języków |
| Portale dla partnerów | Serwisy budujące dokumentację z OpenAPI | Publiczna dokumentacja z kluczami i limitami |
Kolejność jest istotna: punktem wyjścia jest zawsze plik OpenAPI. Wszystko pozostałe da się z niego wygenerować. Dokumentacja pisana ręcznie w edytorze tekstu rozjeżdża się z rzeczywistością w ciągu kilku tygodni, ponieważ nikt nie pamięta, żeby ją poprawić po zmianie w kodzie.
Co musi zawierać dobra dokumentacja
- Sposób uwierzytelnienia — jak zdobyć klucz lub token, jak długo jest ważny, jak go odświeżyć.
- Adresy środowisk testowego i produkcyjnego wraz z informacją, czym się różnią.
- Opis każdego zasobu z listą pól, ich typami i informacją, które są wymagane.
- Przykład żądania i odpowiedzi dla każdej operacji, na realistycznych danych.
- Kompletna lista kodów błędów z wyjaśnieniem, co zrobić w każdym przypadku.
- Limity zapytań — ile żądań na minutę i co się dzieje po ich przekroczeniu.
- Zasady stronicowania przy listach obejmujących wiele rekordów.
- Opis powiadomień zwrotnych — format, sposób weryfikacji podpisu, zasady ponowień.
- Polityka wersjonowania i okres wsparcia starszych wersji.
- Historia zmian z datami i opisem, co się zmieniło.
Najczęściej pomijany element. Kompletna lista błędów. Dokumentacja opisuje odpowiedź poprawną, a integrator dowiaduje się o pozostałych przypadkach dopiero na produkcji. Efekt: integracja przestaje działać przy pierwszej nietypowej sytuacji, bo nikt nie przewidział, że pole może być puste albo że zamówienie może mieć status nieopisany w dokumentacji.
Dokumentacja powstająca razem z kodem
Rozdzielenie kodu i dokumentacji gwarantuje ich rozjechanie. Sprawdzone podejścia są dwa i oba prowadzą do tego samego rezultatu — opis zawsze odpowiada rzeczywistości.
Pierwsze to generowanie opisu z kodu: struktury danych i adresy operacji opisane są w kodzie, a plik OpenAPI powstaje automatycznie przy budowaniu aplikacji. Drugie to projektowanie od dokumentacji: najpierw powstaje plik OpenAPI, uzgodniony z integratorem, a dopiero potem implementacja weryfikowana testami sprawdzającymi zgodność z opisem.
Wariant drugi jest wygodniejszy przy integracjach z partnerem zewnętrznym, bo pozwala uzgodnić kształt interfejsu, zanim ktokolwiek napisze kod. Wariant pierwszy sprawdza się w systemach wewnętrznych, gdzie interfejs zmienia się często i szybciej.
Wersjonowanie — decyzja podejmowana za wcześnie lub za późno
| Podejście | Jak wygląda | Zaleta | Wada |
|---|---|---|---|
| Wersja w adresie | /api/v1/zamowienia | Czytelne, łatwe do zrozumienia | Duplikacja kodu przy wielu wersjach |
| Wersja w nagłówku | Nagłówek żądania | Czysty adres zasobu | Trudniejsze w testowaniu ręcznym |
| Bez wersji | Wyłącznie zmiany zgodne wstecz | Brak kosztu utrzymania wielu wersji | Wymaga dyscypliny, ogranicza swobodę zmian |
Praktyczna zasada: dodawanie nowych pól nie wymaga nowej wersji, usuwanie i zmiana znaczenia istniejących — wymaga zawsze. Nową wersję wprowadza się dopiero wtedy, gdy zmiana psuje istniejące integracje, a nie przy każdej modyfikacji. Jednocześnie warto z góry określić, jak długo stara wersja będzie wspierana, bo bez tego zostaje z Tobą na zawsze.
Środowisko testowe
To element, który najbardziej skraca czas integracji, a najczęściej wypada z zakresu przy cięciu budżetu. Integrator musi mieć możliwość wywołania każdej operacji na danych, których nie boi się zepsuć, i wywołania scenariuszy błędnych — odrzuconej płatności, brakującego towaru, nieprawidłowego klucza.
- Osobne środowisko z danymi przykładowymi, resetowane cyklicznie.
- Klucze testowe wydawane samodzielnie, bez kontaktu z Twoim zespołem.
- Możliwość wywołania scenariuszy błędnych na żądanie, na przykład przez specjalne wartości testowe.
- Narzędzie do podglądu powiadomień zwrotnych, żeby integrator widział, co zostało wysłane.
- Ta sama wersja co na produkcji, z wyraźną informacją o różnicach.
Zapisy w umowie z wykonawcą
Jeżeli zamawiasz system z interfejsem programistycznym, dokumentacja powinna być elementem odbioru, a nie obietnicą. Trzy zapisy w umowie wystarczą, żeby uniknąć najczęstszych sporów.
- Plik OpenAPI jako przedmiot odbioru — aktualny, obejmujący wszystkie operacje, z przykładami i błędami.
- Środowisko testowe udostępnione wraz z dokumentacją i utrzymywane przez ustalony okres.
- Zasady zmian — wyprzedzenie, z jakim wykonawca informuje o zmianach niezgodnych wstecz, oraz minimalny okres wsparcia poprzedniej wersji.
Kryterium odbioru, które działa. Programista spoza projektu, korzystając wyłącznie z dokumentacji i środowiska testowego, wykonuje pełny scenariusz integracji bez zadawania pytań autorom. Jeśli mu się to udaje — dokumentacja jest kompletna. To test tańszy niż jakikolwiek formalny przegląd i znacznie bardziej wiarygodny.
Najczęstsze błędy
- Dokumentacja pisana po zakończeniu projektu, gdy nikt nie pamięta szczegółów decyzji.
- Przykłady z pustymi wartościami zamiast realistycznych danych.
- Brak opisu, co się dzieje przy błędzie integracji lub przekroczeniu limitu.
- Wersjonowanie wprowadzone po pierwszej zmianie psującej integracje, gdy partnerzy już działają na produkcji.
- Dokumentacja w pliku tekstowym wysyłanym pocztą — po miesiącu każdy ma inną wersję.
- Brak historii zmian, przez co integrator nie wie, czy coś się zmieniło od jego wdrożenia.
- Środowisko testowe działające na danych produkcyjnych — ryzyko prawne i techniczne naraz.
Podsumowanie
Dokumentacja interfejsu programistycznego jest narzędziem obniżania kosztu integracji, a nie formalnością. Punktem wyjścia powinien być plik OpenAPI generowany razem z kodem, uzupełniony o realistyczne przykłady, pełną listę błędów i dostępne środowisko testowe.
Przy zamawianiu systemu warto uczynić dokumentację przedmiotem odbioru i sprawdzić ją najprostszym możliwym testem: czy programista spoza projektu przejdzie pełną integrację, korzystając wyłącznie z opisu. Wszystko poniżej tego progu oznacza, że koszt integracji poniesie później Twój zespół, tylko w innej pozycji budżetu.
Najczęstsze pytania
OpenAPI to standard opisu interfejsu — plik tekstowy będący jedynym źródłem prawdy o jego strukturze. Swagger to nazwa zestawu narzędzi wokół tego standardu, przede wszystkim Swagger UI, czyli strony generowanej z pliku OpenAPI, na której można przeglądać operacje i wysyłać zapytania testowe. W praktyce plik jest podstawą, narzędzia są wymienne.
Jeśli powstaje razem z kodem, koszt jest marginalny — to od 5 do 10 procent czasu poświęconego na sam interfejs. Dokumentowanie istniejącego systemu, w którym nikt nie prowadził opisu, to zwykle od kilku do kilkunastu dni pracy, ponieważ trzeba odtworzyć zachowanie z kodu i przetestować przypadki brzegowe.
Nie. Dla integracji wewnętrznych i partnerskich wystarczy dostęp po zalogowaniu. Publiczna dokumentacja ma sens, gdy interfejs jest częścią oferty i chcesz, żeby potencjalni partnerzy mogli ocenić możliwości integracji przed rozmową handlową. W obu przypadkach zawartość powinna być identyczna.
Przy każdej zmianie interfejsu, dlatego jedynym trwałym rozwiązaniem jest generowanie opisu z kodu albo testy sprawdzające zgodność kodu z opisem. Dokumentacja aktualizowana ręcznie rozjeżdża się z rzeczywistością w ciągu kilku tygodni i szybko staje się gorsza niż jej brak, bo wprowadza w błąd.
Trzy zapisy: plik OpenAPI jako przedmiot odbioru wraz z przykładami i listą błędów, udostępnione i utrzymywane środowisko testowe oraz zasady wprowadzania zmian — z jakim wyprzedzeniem wykonawca informuje o zmianach psujących integracje i jak długo wspiera poprzednią wersję.
Bezpłatna wycena Twojego projektu
Opisz w kilku zdaniach, co chcesz zbudować — stronę, aplikację czy sklep. Odpowiadamy w ciągu 24 godzin roboczych konkretną propozycją zakresu i harmonogramu. Konsultacja i wycena są bezpłatne, bez zobowiązań.