Czym jest specyfikacja OpenAPI i jak wygenerować klienta Bird na jej podstawie?

Generator klienta oszczędza kopiowania ścieżek endpointów i pól żądań do własnej biblioteki. Może też wytworzyć modele, które wychwytują nieprawidłowe dane wejściowe, zanim żądanie opuści aplikację.

Skąd pobrać specyfikację Bird?

Pobierz publiczną specyfikację w formacie JSON lub YAML.

Dokumentacja API Bird oraz generatory SDK również korzystają z publicznego bundla. Zapisz pobrany plik razem z konfiguracją generowania, aby móc później odtworzyć klienta.

Specyfikacja OpenAPI definiuje sposób opisu ścieżek, parametrów, uwierzytelniania i struktur odpowiedzi. Generator wykorzystuje ten opis do budowy metod i modeli dla docelowego języka.

Jak wygenerować klienta?

Użyj OpenAPI Generator, aby wygenerować klienta ze specyfikacji JSON Bird. Zainstaluj narzędzie przed uruchomieniem poleceń pobierania, walidacji i generowania.

Ten przykład generuje klienta Ruby w katalogu bird-client:

curl --fail --location https://bird.com/openapi.json --output bird-openapi.json
openapi-generator-cli validate -i bird-openapi.json
openapi-generator-cli generate -i bird-openapi.json -g ruby -o bird-client

Użyj JSON, aby ominąć limit rozmiaru parsera YAML w generatorze. Walidacja może wyświetlić zalecenia nawet wtedy, gdy zakończy się sukcesem. Przejrzyj błędy przed generowaniem.

Zastąp ruby obsługiwanym generatorem dla innego języka. Postępuj zgodnie z wymaganiami instalacyjnymi danego generatora i wygenerowanym plikiem README, aby zbudować lub zainstalować wynik.

Przechowuj wygenerowane pliki oddzielnie od ręcznie pisanego kodu aplikacji. Ponowne generowanie do tego samego katalogu może nadpisać zmiany wprowadzone bezpośrednio w kliencie.

Przewodnik użycia generatora dokumentuje opcje językowe i pliki konfiguracyjne.

Które operacje obejmie klient?

Klient obejmuje operacje HTTP zawarte w publicznym bundlu Bird. Operacja dostępna na innym interfejsie nie otrzyma metody przez generowanie klienta publicznego.

Na przykład rotacja klucza API jest dostępna przez sesję w dashboardzie albo osobisty grant CLI lub MCP. Nie ma jej w publicznym bundlu i nie można jej wywołać kluczem obszaru roboczego API.

Weryfikacja toll-free również ma operacje CLI i MCP poza publicznym bundlem. Sprawdź te interfejsy, zanim uznasz, że brakująca metoda wymaga ręcznej pracy.

Publikowanie Realtime to publiczna operacja HTTP. Subskrybowanie zdarzeń kanału wymaga połączenia WebSocket. Do tej części użyj klienta Realtime.

Jaką obsługę żądań sprawdzić?

Zbadaj wygenerowane środowisko uruchomieniowe, zanim dodasz brakującą obsługę. Różne generatory i konfiguracje zapewniają różne zachowania.

Wygenerowany parametr niekoniecznie zarządza swoją wartością za ciebie. Pole Idempotency-Key nadal wymaga klucza o odpowiednim czasie życia, chyba że środowisko uruchomieniowe dostarcza go samo.

Podobnie konfigurowalny region serwera nie dowodzi, że klient odczytuje go z twojego poświadczenia. Ustaw lub zweryfikuj host przed wysłaniem żądania.

Wygenerować klienta czy użyć Bird SDK?

Użyj Bird SDK, jeśli obsługiwany język i zależności pasują do twojej aplikacji. Wygeneruj klienta, gdy potrzebujesz innego języka lub konwencji generowania w twojej organizacji.

SDK lub bezpośrednie wywołania API porównuje obsługiwane języki, zachowanie przy ponawianiu i domyślne limity czasu.

1. Bird SDK: korzystaj z obsługi żądań, którą Bird dostarcza i utrzymuje.
2. Wygenerowany klient: wybierz język i sprawdź obsługę w środowisku uruchomieniowym przed wdrożeniem.
3. Tylko wygenerowane typy: zachowaj obsługę żądań w istniejącej warstwie HTTP.