sgcOpenAPI はパレットのコンポーネントではなく、コードジェネレーターです。仕様を指定すると Pascal ユニットが 1 つ書き出され、そのユニットをプロジェクトから呼び出します。このページではジェネレーターを一度実行し、生成されたクライアントに対して実際の呼び出しを行います。
始める前に理解しておくべき唯一のことです。sgcOpenAPI は IDE のパレットに何も登録せず、デザイン時パッケージも含まれません。作業の流れは、生成してから使う、です。
sgcOpenAPI.exe は GUI ウィザードとコマンドラインの両方を備えています。仕様を読み取り、.pas ファイルを 1 つ書き出します。
TsgcOpenAPI_Client から派生したクライアントクラス、オペレーションごとに 1 つのメソッド、リクエストとレスポンスのクラス、そしてすぐに使えるシングルトンを返す GetOpenAPIClient 関数を含むユニットです。
生成されたユニットをプロジェクトに追加し、uses 句に入れて、GetOpenAPIClient.YourOperation(...) を呼び出します。結果は、使い終わったら解放するレスポンスオブジェクトです。
AWS、Azure、Google、Microsoft 向けにビルド済みの SDK を含む 5 つの実行時パッケージが同梱されています。これらはコンパイル用でインストール用ではありません。追加するパレットページがないためです。
エディションの列は、コードを制御する define と、それが製品固有の Source/sgcVer.inc の何行目にあるかを示しています。
| 項目 | 内容 |
|---|---|
| IDE | 生成されたコードは Delphi 7 から RAD Studio 13 に対応します。型付きレスポンスオブジェクトには XE7 以降が必要で、同梱のデモは {$IF CompilerVersion >= 28.0} でそれを制御しています。それ未満では、生成されたメソッドは単純な文字列を返します。 |
| C++Builder | 生成されたクライアントはサポート対象外です。sgcHTTP_OpenAPI_Client.pas 全体を制御する SGC_HTTP_OPENAPI は、製品の sgcVer.inc の 702 行目の {$IFNDEF BCB} の内側で定義されるため、C++Builder のビルドではそのユニットが空にコンパイルされます。 |
| エディション | sgcOpenAPI のビルドは下位 2 つの階層に固定されています。その sgcVer.inc の 7 行目から 10 行目は、{$IFDEF SGC_OPENAPI} の後に {$UNDEF SGC_EDT_PRO}、{$UNDEF SGC_EDT_ENT}、{$UNDEF SGC_EDT_ALL} が続き、Core と Standard が定義されたままになります。商用の階層は機能ではなくシート数で分かれています。 |
| サーバーの生成 | 同じビルドは 11 行目で SGC_HTTP_OPENAPI_SERVER を定義するため、ジェネレーターはクライアントに加えてサーバースタブも出力できます。コマンドラインで -s を指定します。 |
| プラットフォーム | ユニットスコープのオペレーティングシステムガードはありません。生成されたクライアントの基底ユニット内にある条件は、通常の {$IFDEF MSWINDOWS} によるインポートとスレッド ID 型の切り替えだけなので、Windows、macOS、Linux、Android、iOS のすべてでコンパイルできます。 |
| ライセンスのアクティベーション | マシンがアクティベートされていない場合は、コマンドラインに -user と -password を渡してください。そうしないと、終了コード 2 で終了します。 |
ジェネレーターは JSON と YAML を受け付け、どちらもローカルで読み取ります。Swagger 2.0 のドキュメントも、ローカルで OpenAPI 3 に変換されます。リモートのコンバーターは -r によるオプトインで、仕様をサードパーティのサーバーにアップロードするため、指定しない限り無効です。
インストールするデザイン時パッケージがないため、他の製品よりもインストールは短く済みます。
ダウンロードしたファイルをフォルダーに展開します。以下ではこのフォルダーを {$DIR} と呼びます。Demos\、Bin\、Source\ が含まれています。
ツール、オプション、ライブラリの順に開きます。生成されたユニットとクライアントの基底クラスが解決されるように、{$DIR}\Source を追加します。IDE にインストールするものはありません。
同梱の SDK が必要な場合は、{$DIR}\Packages\ の下で対応する実行時パッケージを開いてコンパイルします。これらは実行時パッケージなので、インストールではなくコンパイルします。
ウィザードを使う場合は Bin\sgcOpenAPI.exe を実行するか、コマンドラインを使用します。入力 1 つ、出力 1 つで、ユニットができあがります。
生成された .pas を他のユニットの隣に置き、プロジェクトに追加して、uses 句に入れます。統合はこれだけです。
1 つのコマンドラインでユニットを生成し、1 回の呼び出しでそれを使います。3 つ目のタブでは、初日に知っておく価値のあるスイッチを紹介します。
> sgcOpenAPI.exe -i "geolocation.json" -o "geolocation.pas"
File successfully created geolocation.pasどちらのスイッチも必須です。-i にはローカルファイルまたは URL を指定でき、JSON と YAML を受け付けます。-o は書き出す Pascal ユニットです。クリックで操作したい場合は、同じ実行ファイルに GUI ウィザードもあります。生成された .pas をプロジェクトに追加すれば、すぐに使えます。
uses
geolocation; // the unit you just generated
procedure TfrmGeolocation.btnGeolocationClick(Sender: TObject);
var
oResponse: TsgcOpenAPI_Retrieve_the_location_of_an_IP_address_Response;
begin
oResponse := GetOpenAPIClient.Retrieve_the_location_of_an_IP_address(
txtAPIKey.Text, txtIPAddress.Text);
try
if oResponse.IsSuccessful then
memoResponse.Lines.Text :=
'country: ' + oResponse.Successful.Country + #13#10 +
'city: ' + oResponse.Successful.City
else
memoResponse.Lines.Text := oResponse.ResponseError;
finally
oResponse.Free;
end;
end;GetOpenAPIClient はユニット内に生成され、パラメーターを取りません。オペレーションごとに 1 つのメソッドがあり、名前はオペレーション ID から付けられます。レスポンスオブジェクトは自分で解放する必要があり、デモが try finally を使っているのはそのためです。XE7 より前の Delphi では、生成されたメソッドは代わりに単純な文字列を返し、同梱のデモは型付きの経路を {$IF CompilerVersion >= 28.0} で制御しています。
-s generate a server stub instead of a client
-a 3 add an OAuth2 flow to the generated client
(0 none, 1 basic, 2 token, 3 oauth2, 4 jwt)
-u <url> set the base url the generated client uses
-m 1 name methods from summary rather than operationid
(0 operationid, 1 summary, 2 endpoint)
-x <list|file> exclude operations, as "VERB endpoint"
-p generate only the classes the kept operations use
-nc do not create pascal classes
-l show progress messages (errors are always shown)
-user -password activate the licence on this machine大きな仕様では、-x と -p を併用するかどうかで、IDE で開けるユニットになるか開けないユニットになるかが決まります。-r もありますが、仕様全体をサードパーティのコンバーターにアップロードするため、意図的に既定で無効になっています。
生成コマンドは、ツール自身のヘルプに表示される使用法の行です。呼び出しは、同梱のデモ Demos\20.Client\abstractapi.com\geolocation\fGeolocation.pas から、フォームコントロールをリテラルに置き換えたものです。そのデモは仕様を同梱しており、ユニットは自分で生成することを前提としているため、クイックスタートはジェネレーターから始めています。
確認する点は 2 つあり、そのうち 1 つはスクリプトで確認できます。
ツールは File successfully created に続けて出力パスを表示します。エラーは常に標準エラー出力に送られるため、何も書き出さなかった静かな実行は、無音ではありません。
0 は成功、1 はエラー、2 は無効なライセンス、3 は無効なスイッチ、4 は無効な設定ファイル、5 は無効な入力ファイル、6 は無効な出力ファイル、7 は仕様を有効な OpenAPI 3 ドキュメントに変換できなかったことを示します。ビルドスクリプトで確認してください。
生成された .pas をプロジェクトに追加してビルドします。ライブラリパスにある {$DIR}\Source 以外には何にも依存せずにコンパイルできるはずです。
IsSuccessful実行時には、レスポンスオブジェクトが教えてくれます。false の場合は、ResponseError にメッセージ、ResponseCode に HTTP ステータスが入っています。
初回の実行で起きる問題のほとんどは、6 つのいずれかです。
ありません。sgcOpenAPI はコンポーネントを登録せず、デザイン時パッケージも含みません。生成されたユニットが統合のポイントで、GetOpenAPIClient でクライアントにアクセスします。
これは想定どおりです。デモには仕様が同梱されていて、生成されたユニットは含まれていないため、先にジェネレーターを実行します。geolocation のデモには geolocation というユニットが必要で、これは geolocation.json から生成されます。
このマシンでライセンスがアクティベートされていません。コマンドラインに -user と -password を渡してください。
型付きレスポンスには XE7 以降が必要です。同梱のデモは {$IF CompilerVersion >= 28.0} でそれを制御し、古いコンパイラーでは単純な文字列を返すメソッドにフォールバックします。Delphi 7 をサポートする場合は、そのガードを残してください。
SGC_HTTP_OPENAPI は製品の sgcVer.inc の 702 行目の {$IFNDEF BCB} の内側で定義されるため、生成されたクライアントの基底クラスは C++Builder ではまったくコンパイルされません。
終了コード 7 は、ドキュメントを有効な OpenAPI 3 ドキュメントに変換できなかったことを意味します。YAML と Swagger 2.0 はローカルで処理されます。-r によるリモートコンバーターは最後の手段で、ファイル全体を eSeGeCe が管理していないサーバーにアップロードします。
4 つの方向があり、いずれも同じジェネレーターから行います。
-s を指定すると、ジェネレーターは代わりにサーバースタブを出力します。サーバーのデモでは、出力されたオペレーションが仕様に対してどのようにディスパッチされ、検証されるかを確認できます。
AWS、Azure、Google、Microsoft を含む 1,000 以上の仕様がすでに生成され、同梱されています。必要なパッケージをコンパイルすれば、生成の手順は完全に省略できます。
-x は動詞とエンドポイントでオペレーションを除外し、-p は残りのオペレーションが使用しないクラスを取り除きます。大きな仕様では、これが IDE で開けるユニットと開けないユニットの違いになります。
生成されたクライアントには Authentication プロパティがあり、-a で生成時にスキームを選択します。なし、ベーシック、トークン、OAuth2、JWT のいずれかです。
デモプロジェクトはダウンロードに含まれており、Demos\ の下にあります。ビルド済みの SDK、生成されたクライアント、2 つのサーバーサンプルがあります。
| sgcOpenAPI でできること パーサー、ジェネレーター、サーバーコンポーネントを 1 ページで紹介します。 | 開く | |
| パーサー 仕様がどのように読み取られ、検証され、Pascal の型に変換されるかを説明します。 | 開く | |
| サーバーコンポーネント 仕様を利用するのではなく、仕様から API を提供します。 | 開く | |
| 同梱の API コンパイルするだけで使える、ビルド済みの SDK です。 | 開く | |
| 体験版のダウンロード ジェネレーターとソースで、期間限定です。 | 開く | |
| OpenAPI とは 仕様の形式自体が初めての方のための背景説明です。 | 開く |
関連資料：OpenAPI から Delphi クライアントを生成する、スキーマのバンドル、sgcOpenAPI と swagger-codegen の比較、OpenAPI サーバー。各製品にはそれぞれクイックスタートがあり、はじめにのページに一覧があります。
sgcOpenAPI.exe を実行すると Pascal ユニットが 1 つ書き出されるので、そのユニットをプロジェクトに追加します。その中の GetOpenAPIClient が、オペレーションごとに 1 つのメソッドを持つ、すぐに使えるクライアントオブジェクトを返します。
sgcOpenAPI.exe -i "c:\openapi.json" -o "c:\openapi.pas" です。どちらのスイッチも必須です。-i にはローカルファイルまたは URL を指定でき、JSON と YAML のどちらも受け付けます。-o は書き出す Pascal ユニットです。値はコロンの後に続けて指定することもでき、たとえば -i:"c:\openapi.json" のようにします。
TsgcOpenAPIResponse から派生したレスポンスオブジェクトを返します。まず IsSuccessful を読み取ります。false の場合は、ResponseError にメッセージ、ResponseCode に HTTP ステータスが入っています。使い終わったらレスポンスオブジェクトを解放してください。同梱のデモは try finally でそれを行っています。
sgcHTTP_OpenAPI_Client.pas のインターフェース全体を囲む SGC_HTTP_OPENAPI は、製品の sgcVer.inc の 702 行目の {$IFNDEF BCB} の内側で定義されるため、C++Builder ではそのユニットが空にコンパイルされ、生成されたコードには基底クラスがありません。Delphi 向けに生成してください。
{$IF CompilerVersion >= 28.0} でそれを明示しています。この線より上では型付きフィールドを持つレスポンスオブジェクトが得られ、下では同じメソッドが単純な文字列を返します。プロジェクトが両方でビルドできる必要がある場合は、そのガードを残してください。
-s を指定すると、ジェネレーターはクライアントの代わりに、コードファースト属性付きのサーバースタブを出力します。sgcOpenAPI として出荷されるビルドは、sgcVer.inc の 11 行目で SGC_HTTP_OPENAPI_SERVER を定義するため、サーバー側はすべてのライセンスに含まれています。2 つのサーバーデモが Demos\30.Server の下に同梱されています。
-r スイッチは converter.swagger.io の公開コンバーターへのフォールバックを許可し、ヘルプテキストには、これが完全なファイルを eSeGeCe が管理していないサーバーにアップロードすることが明記されています。機密性のあるものには、無効のままにしてください。