Stripe pubblica e mantiene una descrizione OpenAPI 3 ufficiale della propria API. sgcOpenAPI non include un componente Stripe scritto a mano, include un generatore. Esegui sgcOpenAPI.exe una volta sola su quella specifica e ottieni una singola unit Pascal con un metodo per ogni operazione, una classe di response tipizzata per ognuna, e una funzione GetOpenAPIClient che ti consegna un client pronto.
I numeri qui sotto sono stati misurati eseguendo il generatore sull'attuale spec3.json e compilando il risultato, non sono stime.
openapi/spec3.json in github.com/stripe/openapi, dichiarata come OpenAPI 3.0.0. Non serve nessun passaggio di conversione.
419 path diventano 594 metodi e 594 classi di response, insieme a 1.747 classi di modello, in una sola unit di circa 110.000 righe.
Genera con -a 2 e imposta Authentication.Token.BearerToken a run time. Il client invia poi Authorization: Bearer su ogni richiesta.
La unit generata compila pulita su RAD Studio 12 per Win32 con nient'altro nel library path se non la cartella Source di sgcOpenAPI.
Scarica spec3.json dal repository pubblico di Stripe, oppure passa l'URL grezzo direttamente a -i. I due switch sono entrambi obbligatori, tutto il resto ha un valore predefinito.
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i accetta un file locale o un URL, in JSON e in YAML. -o è la unit Pascal da scrivere, e la unit prende il nome da quel file. -a 2 seleziona l'autenticazione a token, che è quello di cui ha bisogno la secret key di Stripe. Lo stesso eseguibile è anche un wizard grafico se lo avvii senza parametri. L'esecuzione termina con exit code 0 quando va a buon fine, e uno script di build può controllare il 5 (file di input), il 6 (file di output) o il 7 (il documento non è stato trasformabile in un documento OpenAPI 3 valido).
Aggiungi al progetto il .pas generato, mettilo in una clausola uses, e l'integrazione finisce lì. Non c'è nessun componente da installare, perché sgcOpenAPI non ne registra nessuno e non distribuisce alcun package di design-time.
Imposta la secret key una volta sola sul client, poi chiama il metodo che il generatore ha battezzato come l'operation id. Gli operation id di Stripe sono già identificatori Pascal validi, quindi PostCharges è esattamente quello che ottieni.
uses stripe; // la unit appena generata 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 non prende parametri e restituisce un client che non devi liberare. La base URL arriva dalla voce servers della specifica, quindi il costruttore generato imposta già https://api.stripe.com/ e la sovrascrivi solo con -u in fase di generazione oppure con SetBaseURL a run time. L'oggetto response invece è tuo, ed è il motivo per cui l'esempio usa un try finally. IsSuccessful è vero per gli status da 200 a 299, mentre ResponseCode e ResponseError raccontano il resto.
È l'unica cosa di Stripe che sorprende, e arriva dalla specifica, non dal generatore.
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;
Tutti e 593 i request body della specifica di Stripe sono dichiarati come application/x-www-form-urlencoded, quindi il parametro generato è const aBody: string e il form lo costruisci tu, nella notazione a parentesi quadre di Stripe. Le response sono un'altra storia: sono dichiarate con schemi nominati, quindi ognuna diventa una classe che leggi attraverso le proprietà.
La unit rispecchia il documento. Non c'è nessuna selezione a monte, quindi tutto quello che Stripe descrive è presente e tutto quello che Stripe tralascia non c'è.
594 in tutto, con il nome preso dall'operation id e rimosso ogni carattere che non può comparire in un identificatore Pascal. -m 1 li nomina a partire dal summary, e -m 2 a partire dall'endpoint.
TsgcOpenAPI_PostCharges_Response discende da TsgcOpenAPIResponse, porta Successful più una proprietà per ogni status di errore dichiarato, ed eredita IsSuccessful, ResponseCode e ResponseError.
Ogni schema dichiarato da Stripe, compreso l'oggetto error condiviso, gli oggetti charge, customer, invoice e subscription, e i payload degli eventi.
I parametri di query opzionali diventano argomenti con valore predefinito nell'ordine di dichiarazione, quindi GetCharges accetta aCreated, aCustomer, aEnding_before, aExpand, aLimit e gli altri senza che tu debba toccare un URL.
I tag presenti nel documento vengono emessi come commenti che raggruppano i metodi dentro l'unica classe. Non diventano classi separate, quindi tutto parte da GetOpenAPIClient.
Le descrizioni scritte da Stripe vengono riportate come commenti Pascal sopra ogni metodo e ogni proprietà, a meno che tu non le disattivi.
Tutte e quattro sono emerse da una generazione reale sulla specifica attuale.
Circa 110.000 righe e 5,5 MB. Compila in fretta, ma l'editor di codice dell'IDE è lento con un file di quelle dimensioni. -x scarta le operazioni che elenchi come "VERB endpoint" e -p rimuove poi le classi che nessuna operazione rimasta usa, ed è la differenza fra una unit che riesci ad aprire e una che non riesci ad aprire.
Riguardano tutti la composizione. In parecchi punti Stripe usa anyOf e oneOf senza una mappatura del discriminatore, quindi la classe generata porta un membro per ogni ramo e il tuo codice decide quale è stato riempito. Il generatore lo segnala schema per schema invece di scegliere in silenzio.
POST /v1/files è l'unica operazione multipart/form-data del documento, e il PostFiles generato accetta solo aExpand. Se ti serve, fai l'upload con TsgcHTTP1Client oppure direttamente con l'API di upload dei file.
Stripe versiona la propria API e rivede spesso la specifica. Fissa la spec3.json da cui hai generato, tienila accanto al progetto, e rigenera quando lo decidi tu. Il generatore è deterministico, quindi lo stesso documento produce la stessa unit.
Come il reader gestisce specifiche reali, incluse le keyword di composizione che producono la maggior parte dei warning di Stripe.
Leggi il post →Specifiche multi-file e puntatori $ref esterni, che vengono risolti prima che il documento venga letto.
Note di rilascio della versione attuale, con le opzioni del generatore e le novità del reader.
Leggi il post →