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.

Autor: zespół Convert Studio — software house z Kielc i Krakowa, projektujemy aplikacje webowe, sklepy i wdrożenia AI dla firm.

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

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.

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

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.

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.