Stripe は自社 API の OpenAPI 3 記述を公式に公開し、保守しています。sgcOpenAPI は手書きの Stripe コンポーネントを同梱していません。同梱しているのはジェネレーターです。その仕様に対して sgcOpenAPI.exe を 1 度実行すれば、操作ごとに 1 つのメソッド、そのすべてに対応する型付きレスポンスクラス、そしてすぐに使えるクライアントを返す GetOpenAPIClient 関数を備えた、1 つの Pascal ユニットが得られます。
以下の数値は、現在の spec3.json に対してジェネレーターを実行し、その出力をコンパイルして計測したものです。推定値ではありません。
github.com/stripe/openapi にある openapi/spec3.json。OpenAPI 3.0.0 として宣言されているため、変換ステップは不要です。
419 個のパスが 594 個のメソッドと 594 個のレスポンスクラスになり、1,747 個のモデルクラスとともに、約 110,000 行の 1 ユニットに収まります。
-a 2 を付けて生成し、実行時に Authentication.Token.BearerToken を設定します。以後、クライアントはすべてのリクエストで Authorization: Bearer を送信します。
生成されたユニットは、ライブラリパスに sgcOpenAPI の Source フォルダー以外を何も置かない状態で、RAD Studio 12 の Win32 向けにクリーンにビルドされます。
Stripe の公開リポジトリから spec3.json をダウンロードするか、生の URL をそのまま -i に渡します。この 2 つのスイッチは必須で、それ以外にはすべて既定値があります。
> sgcOpenAPI.exe -i "spec3.json" -o "stripe.pas" -a 2 File successfully created stripe.pas
-i はローカルファイルまたは URL を受け取り、JSON と YAML の両方に対応します。-o は書き出す Pascal ユニットで、ユニット名はそのファイル名から付けられます。-a 2 はトークン認証を選択するもので、Stripe のシークレットキーにはこれが必要です。同じ実行ファイルは、パラメーターなしで起動すると GUI ウィザードとしても動作します。成功時の終了コードは 0 なので、ビルドスクリプトでは 5（入力ファイル）、6（出力ファイル）、7（ドキュメントを有効な OpenAPI 3 ドキュメントに変換できなかった）を判定できます。
生成された .pas をプロジェクトに追加し、uses 節に書けば、統合はそれで終わりです。インストールするコンポーネントはありません。sgcOpenAPI はコンポーネントを登録せず、設計時パッケージも同梱していないからです。
シークレットキーをクライアントに 1 度だけ設定し、ジェネレーターが操作 ID から名前を付けたメソッドを呼び出します。Stripe の操作 ID はすでに有効な Pascal 識別子なので、得られるメソッドはそのまま PostCharges です。
uses stripe; // 生成したユニット 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 はパラメーターを取らず、解放してはならないクライアントを返します。ベース URL は仕様の servers エントリから取られるため、生成されたコンストラクターはすでに https://api.stripe.com/ を設定しています。上書きするのは、生成時の -u か実行時の SetBaseURL だけです。レスポンスオブジェクトは呼び出し側のものなので、サンプルでは try finally を使っています。IsSuccessful はステータス 200 から 299 で true になり、残りは ResponseCode と ResponseError が伝えます。
Stripe について驚かれる点はこの 1 つで、これはジェネレーターではなく仕様に由来します。
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;
Stripe の仕様にある 593 個のリクエストボディは、そのすべてが application/x-www-form-urlencoded として宣言されています。そのため生成されるパラメーターは const aBody: string となり、フォームは Stripe 独自のブラケット記法で自分で組み立てることになります。レスポンスは事情が違います。名前付きスキーマで宣言されているため、それぞれがプロパティ経由で読み取るクラスになります。
ユニットはドキュメントをそのまま写します。取捨選択は一切行わないので、Stripe が記述しているものはすべて存在し、Stripe が書いていないものは存在しません。
その数 594 個。名前は操作 ID から取り、Pascal 識別子に使えない文字は取り除かれます。-m 1 を使うと代わりにサマリーから、-m 2 ではエンドポイントから名前が付きます。
TsgcOpenAPI_PostCharges_Response は TsgcOpenAPIResponse の子孫で、Successful と、宣言されたエラーステータスごとに 1 つのプロパティを持ち、IsSuccessful、ResponseCode、ResponseError を継承します。
Stripe が宣言するすべてのスキーマ。共有の error オブジェクト、charge、customer、invoice、subscription の各オブジェクト、そしてイベントのペイロードも含まれます。
省略可能なクエリパラメーターは、宣言順に既定値付きの引数になります。GetCharges は aCreated、aCustomer、aEnding_before、aExpand、aLimit などを受け取るので、URL に触れる必要はありません。
ドキュメント内のタグは、単一のクラスの中でメソッドをグループ分けするコメントとして出力されます。別々のクラスにはならないので、すべては GetOpenAPIClient にぶら下がります。
Stripe 自身の説明文は、各メソッドと各プロパティの上に Pascal のコメントとして引き継がれます。無効にすることもできます。
4 点とも、現在の仕様に対する実際の生成実行から得られたものです。
約 110,000 行、5.5 MB です。コンパイルは速いのですが、このサイズのファイルでは IDE のコードエディターが重くなります。-x は "VERB endpoint" の形で列挙した操作を除外し、続いて -p が、残った操作のどれからも使われないクラスを取り除きます。開けるユニットと開けないユニットの差はここにあります。
そのすべてが合成に関するものです。Stripe は多くの箇所で判別子のマッピングなしに anyOf と oneOf を使うため、生成されたクラスは分岐ごとに 1 つのメンバーを持ち、どれが埋まったのかはコードの側で判断します。ジェネレーターは黙って選ぶのではなく、スキーマごとにそのことを報告します。
POST /v1/files はドキュメント中で唯一の multipart/form-data 操作で、生成された PostFiles は aExpand しか受け取りません。必要であれば TsgcHTTP1Client か、ファイルアップロード API を直接使ってアップロードしてください。
Stripe は API にバージョンを付け、仕様も頻繁に改訂します。生成元にした spec3.json を固定し、プロジェクトの隣に置いて、意図したタイミングで再生成してください。ジェネレーターは決定論的なので、同じドキュメントからは同じユニットが得られます。