Specyfikacja OpenAPI
API opisuje samo siebie. Swagger UI wymienia każdy
endpoint z parametrami, odpowiedziami i błędami, pozwala wywołać metodę własnym kluczem i linkuje
surowy dokument — serwowany na żywo pod
/api/q/openapi, więc nie ma jak zostać w tyle za API,
które opisuje.
curl -O https://app.autosignly.eu/api/q/openapi
Co z tym zrobić
- Wygenerować klienta w języku, którego jeszcze nie wydajemy, przez OpenAPI Generator albo narzędzia własnego frameworka
- Pooglądać API, importując dokument do Postmana, Insomnii lub Bruno
- Sprawdzić, co się zmieniło między wydaniami, narzędziem do porównań, np. oasdiff — tym samym, które pilnuje naszego pipeline'u
Wersjonowanie
Wersja siedzi w ścieżce (/publics/v1), nie w dokumencie. W obrębie v1 wyłącznie dodajemy: mogą
pojawić się nowe endpointy, nowe opcjonalne parametry i nowe pola w odpowiedziach, a Twoja
integracja działa dalej. Cokolwiek zepsułoby istniejących klientów, czeka na v2.
Kopia dokumentu jest zacommitowana w repozytorium SDK, gdzie testy każdego oficjalnego klienta porównują z nią nazwy pól — dzięki temu klient, który rozjedzie się z API, wywala własny build, a nie Twój.