Dokumentacja jakości jest ważna, aby interfejsy API były łatwe do zrozumienia, wdrożenia i utrzymania. Skonfigurowaliśmy automatyczną generację dokumentacji w oparciu o specyfikacje OpenAPI przy użyciu Swagger UI i Redoc, dwóch najpopularniejszych narzędzi wizualizacji API.
Pozwala to na zapewnienie programistom interaktywnego interfejsu, w którym można poznać strukturę metod, zapytań testowych i szybko połączyć się z interfejsem API.
Co jest zawarte w dokumentacji
| Sekcja | Opis |
|---|---|
| Punkty końcowe i metody | Pełna lista tras, metody HTTP, parametry, nagłówki |
| Przykładowe żądania/odpowiedzi | Skrypty dla curl, Postman, JavaScript, Python i innych języków |
| Autoryzacja | Obsługa JWT, OAuth2, klucz API bezpośrednio z interfejsu |
| Schematy obiektów | Opis modeli, zagnieżdżonych konstrukcji i wymagań dotyczących danych |
| Kody błędów | Wszystkie możliwe statusy z wyjaśnieniami |
Narzędzia, których używamy
Swagger UI - interaktywna dokumentacja w przeglądarce, z możliwością testowania
Redoc to czytelny, statyczny interfejs idealny do publikowania na stronie
OpenAPI 3. 0/3. 1-The format BOM, na którym wszystko jest oparte
Automatyczna generacja z kodu - adnotacje, opisy, wersje i aktualizacje dokumentacji automatycznie
Eksport do JSON/YAML/HTML
Korzyści dla zespołu i partnerów
Przyspieszenie wejścia na pokład nowych deweloperów
Zmniejszenie błędów integracyjnych
Zawsze aktualna, zsynchronizowana dokumentacja
Szybkie rozpoczęcie integracji bez wsparcia technicznego
Łatwa publikacja dokumentacji na portalach publicznych lub prywatnych
Gdzie szczególnie ważne
Otwarte interfejsy API dla zewnętrznych deweloperów
Wewnętrzne interfejsy API z aktywnym rozwojem
Platformy z integracjami B2B i SDK
Usługi z wymogami dotyczącymi regulacji i zatwierdzania systemów
Swagger i Redoc są standardem dokumentacji API nowej generacji. Stworzymy generację, aktualizację i publikację dokumentacji, aby każdy deweloper mógł rozpocząć integrację z API w ciągu kilku minut.