Stripe publie et maintient une description OpenAPI 3 officielle de son API. sgcOpenAPI ne livre pas de composant Stripe écrit à la main, il livre un générateur. Vous lancez sgcOpenAPI.exe une fois sur cette spécification et vous obtenez une seule unité Pascal avec une méthode par opération, une classe de réponse typée pour chacune d'elles, et une fonction GetOpenAPIClient qui vous rend un client prêt à l'emploi.
Les chiffres ci-dessous ont été mesurés en lançant le générateur sur le spec3.json actuel puis en compilant le résultat, ils ne sont pas estimés.
openapi/spec3.json dans github.com/stripe/openapi, déclaré en OpenAPI 3.0.0. Aucune étape de conversion n'est nécessaire.
419 chemins deviennent 594 méthodes et 594 classes de réponse, à côté de 1 747 classes de modèle, dans une seule unité d'environ 110 000 lignes.
Générez avec -a 2 et définissez Authentication.Token.BearerToken à l'exécution. Le client envoie alors Authorization: Bearer sur chaque requête.
L'unité générée compile sans erreur sur RAD Studio 12 pour Win32, avec rien d'autre sur le chemin des bibliothèques que le dossier Source de sgcOpenAPI.
Téléchargez spec3.json depuis le dépôt public de Stripe, ou passez l'URL brute directement à -i. Les deux commutateurs sont obligatoires, tout le reste a une valeur par défaut.
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i prend un fichier local ou une URL et accepte le JSON et le YAML. -o est l'unité Pascal à écrire, et l'unité porte le nom de ce fichier. -a 2 sélectionne l'authentification par token, ce dont la clé secrète de Stripe a besoin. Le même exécutable est aussi un assistant graphique quand vous le démarrez sans paramètre. L'exécution se termine avec le code de sortie 0 en cas de succès, et un script de build peut tester 5 (fichier d'entrée), 6 (fichier de sortie) ou 7 (le document n'a pas pu être transformé en document OpenAPI 3 valide).
Ajoutez le .pas généré à votre projet, mettez-le dans une clause uses, et c'est toute l'intégration. Il n'y a aucun composant à installer, parce que sgcOpenAPI n'en enregistre aucun et ne livre pas de package de conception.
Définissez la clé secrète une fois sur le client, puis appelez la méthode que le générateur a nommée d'après l'operation id. Les operation ids de Stripe sont déjà des identifiants Pascal valides, donc PostCharges est exactement ce que vous obtenez.
uses stripe; // l'unité que vous venez de générer 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 ne prend aucun paramètre et retourne un client que vous ne libérez pas. L'URL de base sort de l'entrée servers de la spécification, donc le constructeur généré définit déjà https://api.stripe.com/ et vous ne la remplacez qu'avec -u à la génération ou SetBaseURL à l'exécution. L'objet de réponse vous appartient, c'est pourquoi l'exemple utilise un try finally. IsSuccessful est vrai pour les statuts 200 à 299, et ResponseCode et ResponseError portent le reste.
C'est la seule chose à propos de Stripe qui surprend les gens, et elle vient de la spécification plutôt que du générateur.
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;
Chacun des 593 corps de requête de la spécification Stripe est déclaré en application/x-www-form-urlencoded, donc le paramètre généré est const aBody: string et vous construisez le formulaire vous-même, dans la notation à crochets propre à Stripe. Les réponses, c'est une autre histoire : elles sont déclarées avec des schémas nommés, donc chacune devient une classe que vous lisez à travers des propriétés.
L'unité reflète le document. Rien n'est trié à la main, donc tout ce que Stripe décrit est présent et tout ce que Stripe laisse de côté ne l'est pas.
594 au total, nommées d'après l'operation id, tout caractère qui ne peut pas figurer dans un identifiant Pascal étant supprimé. -m 1 les nomme d'après le résumé, et -m 2 d'après l'endpoint.
TsgcOpenAPI_PostCharges_Response descend de TsgcOpenAPIResponse, porte Successful plus une propriété par statut d'erreur déclaré, et hérite de IsSuccessful, ResponseCode et ResponseError.
Chaque schéma déclaré par Stripe, y compris l'objet error partagé, les objets charge, customer, invoice et subscription, et les charges utiles des événements.
Les paramètres de requête optionnels deviennent des arguments avec valeur par défaut, dans l'ordre de déclaration, si bien que GetCharges prend aCreated, aCustomer, aEnding_before, aExpand, aLimit et les autres sans que vous touchiez à une URL.
Les tags du document sont émis comme des commentaires qui regroupent les méthodes à l'intérieur de la classe unique. Ils ne deviennent pas des classes séparées, donc tout part de GetOpenAPIClient.
Les descriptions de Stripe sont reportées en commentaires Pascal au-dessus de chaque méthode et de chaque propriété, sauf si vous les désactivez.
Toutes les quatre sont sorties d'une vraie génération sur la spécification actuelle.
Environ 110 000 lignes et 5,5 Mo. Elle compile vite, mais l'éditeur de code de l'IDE est lent avec un fichier de cette taille. -x retire les opérations que vous listez sous la forme "VERB endpoint" et -p supprime ensuite les classes qu'aucune opération restante n'utilise, ce qui fait la différence entre une unité que vous pouvez ouvrir et une unité que vous ne pouvez pas ouvrir.
Chacun d'eux porte sur la composition. Stripe utilise anyOf et oneOf sans mapping de discriminateur à beaucoup d'endroits, donc la classe générée porte un membre par branche et votre code décide lequel a été rempli. Le générateur le signale schéma par schéma plutôt que de choisir en silence.
POST /v1/files est la seule opération multipart/form-data du document, et le PostFiles généré ne prend que aExpand. Passez par TsgcHTTP1Client ou directement par l'API d'upload de fichiers si vous en avez besoin.
Stripe versionne son API et révise souvent la spécification. Épinglez le spec3.json à partir duquel vous avez généré, gardez-le à côté de votre projet, et regénérez de façon délibérée. Le générateur est déterministe, donc le même document donne la même unité.
Comment le lecteur gère les spécifications réelles, y compris les mots-clés de composition qui produisent la plupart des avertissements Stripe.
Lire le billet →Les spécifications multi-fichiers et les pointeurs $ref externes, qui sont récupérés avant la lecture du document.
Notes de release de la version actuelle, avec les options du générateur et les changements du lecteur.
Lire le billet →