注:
GeneXus 17 Upgrade 6 以降では、OpenAPI 仕様のバージョン 2 とバージョン 3 の両方をサポートしています。OpenAPI インポーターは、スペックがバージョン 2 またはバージョン 3 のどちらを参照しているかを自動的に検出します。
OpenAPI インポートツールの主な目的は、任意の
RESTful Web サービス (GeneXus によって生成できるかどうかを問わない) の
OpenAPI 仕様 (旧称 Swagger RESTful API ドキュメント仕様) をインポートすることです。
OpenAPI インポートツールを使用する際は、RESTful サービスの利用に必要な一部のオブジェクト (
プロシージャー、
構造化データタイプ、
ドメイン) は
ナレッジベースにインポートされます。
このツールを使用する利点は、各種操作、Web サービスを利用するために必要な
メソッド、入出力パラメーター (サービスと応答を呼び出すための HTTP 本文構造) など、
さまざまな情報を Swagger UI ドキュメントから取得する労力を省けることです。
このツールにアクセスするには、
[ ツール ] -> [ アプリケーションの統合 ] -> [ OpenAPI インポート ] メニューオプションを選択します。
ファイルパス/URL: RESTful サービスのドキュメントの URL またはファイルパスを Swagger 形式で入力します。
Swagger 形式: Swagger の仕様に沿って RESTful API を記述したファイルは、JSON オブジェクトとして表され、JSON 標準に準拠します。JSON のスーパーセットである YAML を使用して、Swagger 仕様ファイルを表すこともできます。
GeneXus の REST Web サービスでは、
[ Generate OpenAPI interface ] プロパティを有効にすると Swagger ファイルを取得できます。
モジュール/フォルダ: 自動的に生成されたオブジェクトの格納先として使用されます。
注: ナレッジベースのモジュール化を維持し、オブジェクトに対する不適切な変更を回避するため、YAML ファイルから自動的に作成されたオブジェクトの格納先モジュールを選択することを強くお勧めします。
たとえば、「Customers」という名前の構造が YAML ファイルに含まれている場合、この YAML をインポートしたときに「Customers」SDT が作成されます。ナレッジベースに「Customers」という名前の SDT が既に存在する場合は変更されます (YAML ファイルに含まれている構造に置き換えられます)。インポートされたオブジェクトがモジュール (CRM など) に作成される場合、SDT は「CRM.Customers」として作成され、既存のものを置き換えることはありません。
このツールを使用すると、RESTful サービスを利用するために必要な一部のオブジェクト (プロシージャー、SDT、ドメイン) が KB にインポートされます。
KB にインポートされるオブジェクトの概要を次に示します:
オブジェクト |
フォルダ/モジュール |
目的 |
ApiResponse SDT |
OpenAPICommon |
HTTP 応答構造を定義します。 |
CallApi プロシージャー |
OpenAPICommonP |
パラメーター化されたプロシージャーです。サービス URL と呼び出しのパラメーターを渡すと、HTTP メソッドを実行し、HTTP の結果を返します。 |
VarCharToJsonFormat、
DateTimeToJsonFormat、
DateToJsonFormat、
NumericToJsonFormat |
OpenAPICommon |
補助的なプロシージャーです。 |
AuthREADME (*) |
OpenAPICommon |
OAuth 2.0/OPenID Connect のフローに関してインポートされた仕様から取得される情報を表示するプロシージャーです。 |
ProcessServer (*) |
OpenAPICommon |
OpenAPI 3.0 ではサーバーのテンプレート化が許可されているため、このプロシージャーは、BaseURL の「Api」フォルダの下にあるプロシージャーを (&ServerUrlTemplatingVar パラメーターを使用して) 呼び出すときにユーザーが指定する値の置き換えに対処します。 |
ApiBaseUrl |
<MyModule>\Client |
RESTful サービスの呼び出しに使用される BaseURL を返します。ただし、ほとんどの場合、変更が必要です。
OpenAPI 3.0 仕様がインポートされるとき、このプロシージャーはその仕様に存在するすべてのサーバーを表示し、1 つのサーバー (最初のサーバー) のみをコメント解除します。 |
RESTful サービスのクライアントプロシージャー |
<MyModule>\Api |
サービスを呼び出すためのプロシージャーです。このプロシージャーの名前は、サービスのドキュメントファイル (Swagger) に含まれる operationId* に基づいて選択されます。
*operationId: 操作を識別するために使用される一意の文字列です。この ID は、API で記述されたすべての操作間で一意です。 |
サービスの入出力パラメーターを定義するために必要な SDT |
<MyModule>\Model |
サービスの入出力パラメーターです。 |
(*) バージョン 3 のインポート時にのみ生成されます。
この例では
PetStore 仕様のインポートを示します。
注: これは OpenAPI 3.0 仕様のインポートの例です。バージョン 2 の例は、以前のバージョンを参照してください。
下の図は、例のプロシージャーに関連付けられている YAML ファイルをインポートした後の
KB エクスプローラーの構造です。

コンシューマーのナレッジベースで OpenAPI インポートツールを使用して
PetStore の Swagger ドキュメントを調査すると、PetStoreModule\Api パスに
CreateUsersWithListInput というプロシージャーが自動的に生成されます。この例では、"PetStoreModule" がモジュールです。ツールで生成されたオブジェクトをインポートするように設定されています。
調査中のサービスに対応する Swagger ドキュメントの一部を次に示します。なお、RESTful サービスを利用するためのプロシージャーの名前は operationId の値に基づいて決定されます。
/user/createWithList:
post:
tags:
- user
summary: Creates list of users with given input array
description: Creates list of users with given input array
operationId: createUsersWithListInput
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
responses:
'200':
description: Successful operation
content:
application/xml:
schema:
$ref: '#/components/schemas/User'
application/json:
schema:
$ref: '#/components/schemas/User'
default:
description: successful operation
User は、RequestBody と Response の両方に対してツールによって自動的に生成される SDT です (この場合、タイプと一致するが、常に一致するとは限らない)。
次のパラメーター情報も Swagger ファイルから取得されます。
components:
schemas:
...
User:
type: object
properties:
id:
type: integer
format: int64
example: 10
username:
type: string
example: theUser
firstName:
type: string
example: John
lastName:
type: string
example: James
email:
type: string
example: john@email.com
password:
type: string
example: '12345'
phone:
type: string
example: '12345'
userStatus:
type: integer
description: User Status
format: int32
example: 1
xml:
name: user
次の
Parm ルールは、サービスを呼び出すためのスタブである
CreateUsersWithListInput コンシューマーオブジェクトに生成されます。
parm(in:&ServerUrlTemplatingVar, in:&body, out:&UserOUT, out:&HttpMessage, out:&IsSuccess);
&ServerUrlTemplatingVar パラメーターはすべてのコンシューマープロシージャーに存在します。これは「Properties」タイプの変数であり、BaseURL でテンプレート変数に値を割り当てる役割を持ちます。例えば、次の BaseURL があるとします:
{scheme}://{host}:8082/APIObjectPlayground.NETCoreEnvironment/rest
&ServerUrlTemplatingVar は次のように設定できます:
&ServerUrlTemplatingVar.Set("scheme","https")
&ServerUrlTemplatingVar.Set("host","example")
その結果、BaseURL は次のようになります:
https://example:8082/APIObjectPlayground.NETCoreEnvironment/rest
このテンプレート化の値の割り当てを簡単にするために、割り当て可能な値の範囲を持つ列挙型ドメインを生成できます。例えば、これらのドメインの名前を「TemplateServer_{key_name}」とします。前述のケースで、「scheme」キーに対してドメインが生成された場合、その名前は「TemplateServer_scheme」になります。これは、仕様で列挙が指定されている場合にのみ行われます。
したがって、サービスを呼び出すために必要な作業は、
CreateUsersWithListInput コンシューマーオブジェクトを呼び出すことです。そのためには、対応するパラメーターを渡して、結果を処理します:
PetStoreModule.CreateUsersWithListInput(&ServerUrlTemplatingVar,&User,&UserOUT,&HttpMessage,&IsSuccess)
if &IsSuccess
msg("Success!!")
else
msg("There was an error! ")
endif
msg("API return: " + &UserOUT.ToJson())
msg("HTTP Message " + &HttpMessage.Id + " " + &HttpMessage.Description)
&User は、以下のような構造を持ち、
[ Collection ] プロパティが True に設定されている
Data Provider オブジェクトです。
User{
id = 1000
username = 'TheUser'
firstName = 'Luis'
lastName = 'Murillo'
email = 'lmur@gmail.com'
password = ''
phone = '1234'
userStatus = 1
}
この方法は、入出力パラメーターを手動で定義し、HttpClient データタイプを使用して HTTP メソッドを実行する場合よりもはるかに簡単です。このタスクは、OpenAPI インポートツールによって実行され、必要なコードを自動的に生成します。
API へのセキュリティの追加が必要な場合もあります。これを行うには、CallApi プロシージャーのどこかに以下の行を追加する必要があります:
&httpClient.AddAuthentication(&authentication_method, "", &user, &password)
AddAuthentication メソッドが変数 &httpClient に適用されます。この変数は、
HttpClient データタイプです。
変数 &authentication_method は数値である必要があります。0 から 3 の任意の値で希望するセキュリティ レベルを指定できます。さらに、変数 &user と &password を定義して、それぞれ値を割り当てる必要があります。この情報を以下のように直接追加することもできます:
&httpClient.AddAuthentication(0, "", "MyUser", "MyPassword")
値 "0" は認証タイプが標準であることを意味します。
REST サービスとして公開されているビジネスコンポーネントを使用してデータを挿入する方法