最近のアクセス:
OpenAPI インポートツール

: GeneXus 17 Upgrade 6 以降では、OpenAPI のバージョン 2 およびバージョン 3 両方の仕様をサポートします。仕様がバージョン 2 と 3 のどちらを参照しているかは OpenAPI インポーターが自動的に検出します。
OpenAPI インポートツールの主な目的は、任意の RESTful Web サービス (GeneXus によって生成できるどうかを問わない) の Open API RESTful API ドキュメント (旧称 Swagger RESTful API ドキュメント仕様) を調査することです。
OpenAPI インポートツールを使用して情報を取得すると、RESTful サービスを利用するために必要な一部のオブジェクト (ProcedureSDTDomain) がナレッジベースに統合されるため、コンシューマーの実装がはるかに容易になります。その後、「REST サービスとして公開されているビジネスコンポーネントを使用してデータを挿入する方法」のチュートリアルを進めやすくなります。
OpenAPI インポートツールを使用する利点は、各種操作、Web サービスを利用するために必要な HTTP のメソッド、入出力パラメーター (サービス応答を呼び出すための HTTP 本文構造) など、さまざまな情報を Swagger UI ドキュメントから取得する労力を省けることです。
GeneXus の REST Web サービスの OpenAPI ドキュメントは、[ Generate OpenAPI interface ] プロパティを使用して取得することに留意してください。
このツールにアクセスするには、 [ ツール ] > [ アプリケーションの統合 ] > [ OpenAPI インポート ] メニューオプションを選択します。
イメージ:37611.png

OpenAPI インポートツールのダイアログ

ファイルパス/URL:  RESTful サービスのドキュメントの URL またはファイルパスを Swagger 形式で入力します。
Swagger 形式:
Swagger の仕様に沿って RESTful API を記述したファイルは、JSON オブジェクトとして表され、JSON 標準に準拠します。JSON のスーパーセットである YAML を使用して、Swagger 仕様ファイルを表すこともできます。
GeneXus の REST Web サービスでは、[ Generate OpenAPI interface ] プロパティを有効にすると Swagger ファイルを取得できます。
モジュール/フォルダ: 自動的に生成されたオブジェクトの格納先として使用されます。
イメージ:37609.png
注: ナレッジベースのモジュール化を維持し、オブジェクトに対する不適切な変更を回避するため、YAML ファイルから自動的に作成されたオブジェクトの格納先モジュールを選択することを強くお勧めします。
たとえば、「Customers」という名前の構造が YAML ファイルに含まれている場合、この YAML をインポートしたときに「Customers」SDT が作成されます。ナレッジベースに「Customers」という名前の SDT が既に存在する場合は変更されます (YAML ファイルに含まれている構造に置き換えられます)。インポートされたオブジェクトがモジュール (CRM など) に作成される場合、SDT は「CRM.Customers」として作成され、既存のものを置き換えることはありません。

OpenAPI インポートツールの使用結果

このツールを使用すると、RESTful サービスを利用するために必要な一部のオブジェクト (プロシージャー、SDT、ドメイン) がナレッジベースに統合されます。
ナレッジベースに統合されるオブジェクトの概要を次に示します:
オブジェクト フォルダ/モジュール 目的
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 で (&ServerUrlTemplatingVar パラメーターを通じて)「API」フォルダの下にあるプロシージャーを呼び出す場合、ユーザーによって与えられた値をこのプロシージャーが置き換えます。
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 の例については、過去のバージョンを参照してください。

KB エクスプローラーの構造の例

下の図は、例のプロシージャーに関連付けられている YAML ファイルをインポートした後の KB エクスプローラーの構造です。
イメージ:49285.png
コンシューマーのナレッジベースで OpenAPI インポートツールを使用して PetStore の Swagger ドキュメントを調査すると、PetStoreModule\Api パスに CreateUsersWithListInput というプロシージャーが自動的に生成されます。この例では、「PetStoreModule」がモジュールです。ツールで生成されたオブジェクトをここにインポートするように指定しています。
調査対象のサービスに対応する Swagger ドキュメントの一部を次に示します。なお、RESTful サービスを利用するためのプロシージャーの名前は operationId の値に基づいて決定されます。
/user/createWithList:
    post: 
      tags:
        - user
      summary: 入力のアレイを使ってユーザーのリストを作成
      description: 入力のアレイを使ってユーザーのリストを作成
      operationId: createUsersWithListInput
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/User'
      responses:
        '200':
          description: 操作が正常に終了
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: 操作が正常に終了
ユーザーは、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: ユーザーの状態
          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_{キー名}」という名前が付けられます。先ほどの例に戻ると、「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)
この方法は、入出力パラメーターを手動で定義し、HttpClient データタイプを使用して HTTP メソッドを実行する場合よりもはるかに簡単です。このタスクは、OpenAPI インポートツールによって実行され、必要なコードを自動的に生成します。





サブページ
Created: 18/10/29 01:05 by Admin Last update: 22/03/14 00:43 by Admin
カテゴリ
Powered by GXwiki 3.0