Stripe publiceert en onderhoudt een officiële OpenAPI 3-beschrijving van zijn API. sgcOpenAPI levert geen met de hand geschreven Stripe-component, het levert een generator. Je draait sgcOpenAPI.exe één keer over die specificatie en je krijgt één Pascal-unit met één methode per operatie, een getypeerde response-klasse voor elk daarvan, en een GetOpenAPIClient-functie die je een kant-en-klare client geeft.
De cijfers hieronder zijn gemeten door de generator over de huidige spec3.json te draaien en het resultaat te compileren, niet geschat.
openapi/spec3.json in github.com/stripe/openapi, opgegeven als OpenAPI 3.0.0. Er is geen conversiestap nodig.
419 paths worden 594 methodes en 594 response-klassen, naast 1.747 modelklassen, in één unit van ongeveer 110.000 regels.
Genereer met -a 2 en zet Authentication.Token.BearerToken tijdens runtime. De client stuurt daarna Authorization: Bearer mee bij elk verzoek.
De gegenereerde unit bouwt schoon op RAD Studio 12 voor Win32, met niets op het library-pad behalve de map Source van sgcOpenAPI.
Download spec3.json uit de publieke repository van Stripe, of geef de raw-URL rechtstreeks aan -i mee. Beide schakelaars zijn verplicht, al het andere heeft een standaardwaarde.
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i neemt een lokaal bestand of een URL en accepteert JSON en YAML. -o is de Pascal-unit die geschreven wordt, en de unit krijgt de naam van dat bestand. -a 2 kiest token-authenticatie, en dat is wat de secret key van Stripe nodig heeft. Hetzelfde uitvoerbare bestand is ook een GUI-wizard als je het zonder parameters start. De run eindigt bij succes met exitcode 0, en een buildscript kan testen op 5 (invoerbestand), 6 (uitvoerbestand) of 7 (het document kon niet worden omgezet naar een geldig OpenAPI 3-document).
Voeg de gegenereerde .pas toe aan je project, zet hem in een uses-clausule, en dat is de hele integratie. Er is geen component te installeren, want sgcOpenAPI registreert er geen en levert geen design-time package.
Stel de secret key eenmaal in op de client, en roep dan de methode aan die de generator naar de operation-id heeft vernoemd. De operation-id’s van Stripe zijn al geldige Pascal-identifiers, dus PostCharges is precies wat je krijgt.
uses stripe; // de unit die je zojuist genereerde 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 neemt geen parameters en geeft een client terug die je niet vrijgeeft. De basis-URL komt uit de servers-entry in de specificatie, dus de gegenereerde constructor zet https://api.stripe.com/ er al in en je overschrijft die alleen met -u bij het genereren of met SetBaseURL tijdens runtime. Het response-object is van jou, en daarom gebruikt het voorbeeld een try finally. IsSuccessful is waar voor status 200 tot en met 299, en ResponseCode en ResponseError dragen de rest.
Dit is het ene punt aan Stripe dat mensen verrast, en het komt uit de specificatie en niet uit de 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;
Alle 593 request-bodies in de specificatie van Stripe zijn opgegeven als application/x-www-form-urlencoded, dus de gegenereerde parameter is const aBody: string en je bouwt het formulier zelf op, in de eigen haakjesnotatie van Stripe. Met responses zit het anders: die zijn opgegeven met benoemde schema’s, dus elke response wordt een klasse die je via properties uitleest.
De unit spiegelt het document. Er wordt niets geselecteerd, dus alles wat Stripe beschrijft zit erin en alles wat Stripe weglaat zit er niet in.
594 stuks, vernoemd naar de operation-id, waarbij elk teken dat niet in een Pascal-identifier past is verwijderd. Met -m 1 worden ze naar de summary vernoemd, en met -m 2 naar het endpoint.
TsgcOpenAPI_PostCharges_Response stamt af van TsgcOpenAPIResponse, draagt Successful plus één property per opgegeven foutstatus, en erft IsSuccessful, ResponseCode en ResponseError.
Elk schema dat Stripe opgeeft, inclusief het gedeelde error-object, de objecten charge, customer, invoice en subscription, en de event-payloads.
Optionele queryparameters worden argumenten met een standaardwaarde, in de volgorde waarin ze zijn opgegeven, dus GetCharges neemt aCreated, aCustomer, aEnding_before, aExpand, aLimit en de rest zonder dat je een URL aanraakt.
De tags in het document komen eruit als commentaar dat de methodes binnen die ene klasse groepeert. Ze worden geen aparte klassen, dus alles hangt aan GetOpenAPIClient.
De eigen beschrijvingen van Stripe worden meegenomen als Pascal-commentaar boven elke methode en property, tenzij je ze uitzet.
Alle vier komen uit een echte generatierun over de huidige specificatie.
Ongeveer 110.000 regels en 5,5 MB. Hij compileert snel, maar de code-editor van de IDE is traag bij een bestand van dat formaat. -x laat operaties weg die je opgeeft als "VERB endpoint" en -p haalt daarna de klassen weg die geen enkele overgebleven operatie gebruikt, en dat is het verschil tussen een unit die je kunt openen en een die je niet kunt openen.
Ze gaan stuk voor stuk over compositie. Stripe gebruikt op veel plaatsen anyOf en oneOf zonder discriminator-mapping, dus de gegenereerde klasse draagt één member per tak en jouw code bepaalt welke er gevuld is. De generator meldt dat per schema in plaats van stilzwijgend te kiezen.
POST /v1/files is de enige multipart/form-data-operatie in het document, en de gegenereerde PostFiles neemt alleen aExpand. Upload via TsgcHTTP1Client of rechtstreeks via de file-upload-API als je dat nodig hebt.
Stripe versioneert zijn API en herziet de specificatie vaak. Pin de spec3.json waaruit je hebt gegenereerd, houd hem naast je project, en genereer bewust opnieuw. De generator is deterministisch, dus hetzelfde document geeft dezelfde unit.
Hoe de lezer echte specificaties afhandelt, inclusief de compositie-keywords die de meeste Stripe-waarschuwingen opleveren.
Lees post →Multi-file-specificaties en externe $ref-pointers, die worden opgehaald voordat het document wordt gelezen.
Release-notes voor de huidige versie, met de generator-opties en de wijzigingen in de lezer.
Lees post →