Stripe veröffentlicht und pflegt eine offizielle OpenAPI-3-Beschreibung seiner API. sgcOpenAPI liefert keine handgeschriebene Stripe-Komponente mit, sondern einen Generator. Du lässt sgcOpenAPI.exe einmal über diese Spezifikation laufen und bekommst eine einzige Pascal-Unit mit einer Methode pro Operation, einer typisierten Response-Klasse für jede davon und einer Funktion GetOpenAPIClient, die dir einen fertigen Client liefert.
Die Zahlen weiter unten sind nicht geschätzt, sondern gemessen: der Generator lief über die aktuelle spec3.json und das Ergebnis wurde kompiliert.
openapi/spec3.json in github.com/stripe/openapi, deklariert als OpenAPI 3.0.0. Ein Konvertierungsschritt ist nicht nötig.
Aus 419 Pfaden werden 594 Methoden und 594 Response-Klassen, dazu 1.747 Modellklassen, in einer einzigen Unit von rund 110.000 Zeilen.
Generiere mit -a 2 und setze zur Laufzeit Authentication.Token.BearerToken. Der Client sendet dann bei jedem Request Authorization: Bearer.
Die generierte Unit baut sauber unter RAD Studio 12 für Win32, mit nichts im Bibliothekspfad außer dem Source-Ordner von sgcOpenAPI.
Lade spec3.json aus Stripes öffentlichem Repository herunter oder übergib die Roh-URL direkt an -i. Beide Schalter sind Pflicht, alles andere hat einen Vorgabewert.
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i nimmt eine lokale Datei oder eine URL und akzeptiert JSON wie YAML. -o ist die zu schreibende Pascal-Unit, und die Unit wird nach dieser Datei benannt. -a 2 wählt die Token-Authentifizierung, genau das, was Stripes Secret Key braucht. Dieselbe ausführbare Datei ist auch ein GUI-Assistent, wenn du sie ohne Parameter startest. Bei Erfolg endet der Lauf mit Exit-Code 0, und ein Build-Skript kann auf 5 (Eingabedatei), 6 (Ausgabedatei) oder 7 (das Dokument ließ sich nicht in ein gültiges OpenAPI-3-Dokument überführen) prüfen.
Nimm die generierte .pas ins Projekt auf, trag sie in eine uses-Klausel ein, und das ist die ganze Integration. Es gibt keine Komponente zu installieren, denn sgcOpenAPI registriert keine und liefert kein Design-Time-Package mit.
Setze den Secret Key einmal auf dem Client und ruf dann die Methode auf, die der Generator nach der Operation-ID benannt hat. Stripes Operation-IDs sind bereits gültige Pascal-Bezeichner, deshalb bekommst du genau PostCharges.
uses stripe; // die gerade generierte Unit 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 nimmt keine Parameter und liefert einen Client zurück, den du nicht freigibst. Die Basis-URL stammt aus dem servers-Eintrag der Spezifikation, der generierte Konstruktor setzt also bereits https://api.stripe.com/, und du überschreibst sie nur mit -u beim Generieren oder mit SetBaseURL zur Laufzeit. Das Response-Objekt gehört dir, deshalb verwendet das Beispiel ein try finally. IsSuccessful ist bei Status 200 bis 299 wahr, und ResponseCode und ResponseError tragen den Rest.
Das ist die eine Sache an Stripe, die Leute überrascht, und sie kommt aus der Spezifikation, nicht aus dem Generator.
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;
Jeder der 593 Request-Bodies in Stripes Spezifikation ist als application/x-www-form-urlencoded deklariert, der generierte Parameter lautet deshalb const aBody: string und du baust das Formular selbst, in Stripes eigener Klammer-Notation. Bei den Antworten sieht es anders aus: dort stehen benannte Schemas, jede Antwort wird also zu einer Klasse, die du über Eigenschaften ausliest.
Die Unit spiegelt das Dokument. Nichts wird kuratiert, alles was Stripe beschreibt ist also da, und alles was Stripe auslässt fehlt.
594 Stück, benannt nach der Operation-ID, wobei jedes Zeichen entfällt, das in einem Pascal-Bezeichner nicht vorkommen darf. -m 1 benennt sie stattdessen nach der Zusammenfassung, -m 2 nach dem Endpunkt.
TsgcOpenAPI_PostCharges_Response stammt von TsgcOpenAPIResponse ab, trägt Successful plus eine Eigenschaft pro deklariertem Fehlerstatus und erbt IsSuccessful, ResponseCode und ResponseError.
Jedes Schema, das Stripe deklariert, einschließlich des gemeinsamen error-Objekts, der Objekte charge, customer, invoice und subscription sowie der Event-Payloads.
Optionale Query-Parameter werden in Deklarationsreihenfolge zu Argumenten mit Vorgabewert. GetCharges nimmt also aCreated, aCustomer, aEnding_before, aExpand, aLimit und den Rest entgegen, ohne dass du eine URL anfasst.
Die Tags aus dem Dokument werden als Kommentare ausgegeben, die die Methoden innerhalb der einen Klasse gruppieren. Zu eigenen Klassen werden sie nicht, alles hängt also an GetOpenAPIClient.
Stripes eigene Beschreibungen werden als Pascal-Kommentare über jede Methode und jede Eigenschaft übernommen, sofern du das nicht abschaltest.
Alle vier stammen aus einem echten Generierungslauf über die aktuelle Spezifikation.
Rund 110.000 Zeilen und 5,5 MB. Das Kompilieren geht schnell, aber der Code-Editor der IDE wird bei einer Datei dieser Größe langsam. -x lässt Operationen weg, die du als "VERB endpoint" aufführst, und -p entfernt danach die Klassen, die keine verbliebene Operation mehr nutzt. Das ist der Unterschied zwischen einer Unit, die du öffnen kannst, und einer, die du nicht öffnen kannst.
Bei jeder einzelnen geht es um Composition. Stripe verwendet an vielen Stellen anyOf und oneOf ohne Discriminator-Mapping, die generierte Klasse trägt deshalb ein Member pro Zweig und dein Code entscheidet, welches befüllt wurde. Der Generator sagt das pro Schema, statt still eine Variante auszuwählen.
POST /v1/files ist die einzige multipart/form-data-Operation im Dokument, und das generierte PostFiles nimmt nur aExpand entgegen. Lade über TsgcHTTP1Client oder direkt über die File-Upload-API hoch, wenn du das brauchst.
Stripe versioniert seine API und überarbeitet die Spezifikation häufig. Pinne die spec3.json, aus der du generiert hast, leg sie neben dein Projekt und generiere bewusst neu. Der Generator ist deterministisch, dasselbe Dokument ergibt also dieselbe Unit.
Wie der Parser reale Spezifikationen handhabt, einschließlich der Composition-Keywords, aus denen die meisten Stripe-Warnungen stammen.
Beitrag lesen →Multi-Datei-Spezifikationen und externe $ref-Verweise, die eingesammelt werden, bevor das Dokument gelesen wird.
Release Notes zur aktuellen Version, mit den Generator-Optionen und den Änderungen am Parser.
Beitrag lesen →