Stripe publikuje i utrzymuje oficjalny opis swojego API w formacie OpenAPI 3. sgcOpenAPI nie dostarcza ręcznie napisanego komponentu Stripe, dostarcza generator. Uruchamiasz sgcOpenAPI.exe raz na tej specyfikacji i dostajesz pojedynczą jednostkę Pascala z jedną metodą na operację, typowaną klasą odpowiedzi dla każdej z nich oraz funkcją GetOpenAPIClient, która zwraca gotowego klienta.
Poniższe liczby zostały zmierzone przez uruchomienie generatora na bieżącym pliku spec3.json i skompilowanie wyniku, nie są szacunkami.
openapi/spec3.json w github.com/stripe/openapi, zadeklarowana jako OpenAPI 3.0.0. Żaden krok konwersji nie jest potrzebny.
419 ścieżek zamienia się w 594 metody i 594 klasy odpowiedzi, obok 1747 klas modeli, w jednej jednostce liczącej około 110 000 wierszy.
Generuj z -a 2 i ustaw Authentication.Token.BearerToken w czasie działania. Klient wysyła wtedy Authorization: Bearer przy każdym żądaniu.
Wygenerowana jednostka buduje się bez błędów w RAD Studio 12 dla Win32, przy czym na ścieżce bibliotek nie ma nic poza folderem Source sgcOpenAPI.
Pobierz spec3.json z publicznego repozytorium Stripe albo przekaż surowy adres URL prosto do -i. Oba przełączniki są obowiązkowe, wszystko inne ma wartość domyślną.
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i przyjmuje plik lokalny lub adres URL i akceptuje JSON oraz YAML. -o to jednostka Pascala do zapisania, a jednostka bierze nazwę od tego pliku. -a 2 wybiera uwierzytelnianie tokenem, czego wymaga tajny klucz Stripe. Ten sam plik wykonywalny jest też kreatorem graficznym, kiedy uruchomisz go bez parametrów. Uruchomienie kończy się kodem wyjścia 0 przy powodzeniu, a skrypt budowania może sprawdzić 5 (plik wejściowy), 6 (plik wyjściowy) lub 7 (dokumentu nie dało się zamienić w poprawny dokument OpenAPI 3).
Dodaj wygenerowany plik .pas do projektu, wpisz go do klauzuli uses i to cała integracja. Nie ma komponentu do zainstalowania, ponieważ sgcOpenAPI nie rejestruje żadnego i nie dostarcza pakietu design-time.
Ustaw tajny klucz raz na kliencie, potem wywołaj metodę, którą generator nazwał od identyfikatora operacji. Identyfikatory operacji Stripe są już poprawnymi identyfikatorami Pascala, więc dostajesz dokładnie PostCharges.
uses stripe; // właśnie wygenerowana jednostka procedure TfrmStripe.btnChargeClick(Sender: TObject); var oResponse: TsgcOpenAPI_PostCharges_Response; begin GetOpenAPIClient.Authentication.Token.BearerToken := 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'; oResponse := GetOpenAPIClient.PostCharges( 'amount=2000¤cy=usd&source=tok_visa&description=Order+1234'); try if oResponse.IsSuccessful then memoLog.Lines.Text := 'charge : ' + oResponse.Successful.Id + #13#10 + 'status : ' + oResponse.Successful.Status + #13#10 + 'paid : ' + BoolToStr(oResponse.Successful.Paid, True) else memoLog.Lines.Text := IntToStr(oResponse.ResponseCode) + ' ' + oResponse.ResponseError; finally oResponse.Free; end; end;
GetOpenAPIClient nie przyjmuje parametrów i zwraca klienta, którego nie zwalniasz. Bazowy adres URL pochodzi z wpisu servers w specyfikacji, więc wygenerowany konstruktor ustawia już https://api.stripe.com/, a nadpisujesz go tylko przełącznikiem -u przy generowaniu albo metodą SetBaseURL w czasie działania. Obiekt odpowiedzi należy do ciebie, dlatego przykład używa try finally. IsSuccessful jest prawdą dla statusów od 200 do 299, a ResponseCode i ResponseError niosą całą resztę.
To jedyna rzecz w Stripe, która zaskakuje ludzi, i bierze się ze specyfikacji, a nie z generatora.
var oCustomer: TsgcOpenAPI_PostCustomers_Response; oSub: TsgcOpenAPI_PostSubscriptions_Response; begin oCustomer := GetOpenAPIClient.PostCustomers( 'email=jane@example.com&payment_method=pm_card_visa'); try if not oCustomer.IsSuccessful then raise Exception.Create(oCustomer.ResponseError); oSub := GetOpenAPIClient.PostSubscriptions( 'customer=' + oCustomer.Successful.Id + '&items[0][price]=price_1JxYzZAbCdEfGhIj'); try memoLog.Lines.Add(oSub.Successful.Id); finally oSub.Free; end; finally oCustomer.Free; end; end;
Każde z 593 ciał żądań w specyfikacji Stripe jest zadeklarowane jako application/x-www-form-urlencoded, więc wygenerowany parametr to const aBody: string i formularz budujesz sam, we własnej notacji nawiasowej Stripe. Z odpowiedziami jest inaczej: są zadeklarowane nazwanymi schematami, więc każda staje się klasą, którą czytasz przez właściwości.
Jednostka odzwierciedla dokument. Nic nie jest ręcznie dobierane, więc wszystko, co Stripe opisuje, jest obecne, a czego Stripe nie opisuje, tego nie ma.
594 metody, nazwane od identyfikatora operacji, z usunięciem każdego znaku, który nie może wystąpić w identyfikatorze Pascala. -m 1 nazywa je od podsumowania, a -m 2 od endpointu.
TsgcOpenAPI_PostCharges_Response dziedziczy po TsgcOpenAPIResponse, niesie Successful plus jedną właściwość na każdy zadeklarowany status błędu i przejmuje IsSuccessful, ResponseCode oraz ResponseError.
Każdy schemat zadeklarowany przez Stripe, w tym wspólny obiekt error, obiekty charge, customer, invoice i subscription oraz ładunki zdarzeń.
Opcjonalne parametry zapytania stają się argumentami z wartościami domyślnymi, w kolejności deklaracji, więc GetCharges przyjmuje aCreated, aCustomer, aEnding_before, aExpand, aLimit i resztę, bez dotykania adresu URL.
Tagi z dokumentu są emitowane jako komentarze, które grupują metody wewnątrz jednej klasy. Nie stają się osobnymi klasami, więc wszystko wisi na GetOpenAPIClient.
Własne opisy Stripe są przenoszone jako komentarze Pascala nad każdą metodą i właściwością, chyba że je wyłączysz.
Wszystkie cztery wyszły z rzeczywistego uruchomienia generatora na bieżącej specyfikacji.
Około 110 000 wierszy i 5,5 MB. Kompiluje się szybko, ale edytor kodu w IDE działa wolno przy pliku tej wielkości. -x usuwa operacje wypisane jako "VERB endpoint", a -p usuwa potem klasy, których nie używa żadna pozostała operacja, i to jest różnica między jednostką, którą da się otworzyć, a taką, której się nie da.
Każde z nich dotyczy kompozycji. Stripe używa anyOf i oneOf bez mapowania dyskryminatora w wielu miejscach, więc wygenerowana klasa niesie jeden składnik na gałąź, a twój kod decyduje, który został wypełniony. Generator mówi o tym przy każdym schemacie, zamiast wybierać po cichu.
POST /v1/files to jedyna operacja multipart/form-data w dokumencie, a wygenerowana metoda PostFiles przyjmuje tylko aExpand. Jeśli tego potrzebujesz, prześlij plik przez TsgcHTTP1Client albo bezpośrednio przez API przesyłania plików.
Stripe wersjonuje swoje API i często poprawia specyfikację. Przypnij plik spec3.json, z którego generowałeś, trzymaj go obok projektu i generuj ponownie świadomie. Generator jest deterministyczny, więc ten sam dokument daje tę samą jednostkę.
Jak czytnik obsługuje rzeczywiste specyfikacje, w tym słowa kluczowe kompozycji, które dają większość ostrzeżeń Stripe.
Czytaj wpis →Specyfikacje z wieloma plikami i zewnętrzne wskaźniki $ref, wciągane przed odczytaniem dokumentu.
Notatki wydania dla bieżącej wersji, z opcjami generatora i zmianami w czytniku.
Czytaj wpis →