コマンドラインを使用したWrapper API仕様およびPostmanコレクションの生成

ブロックチェーン・アプリケーション・ビルダーを使用して、フィルタされたトークン、アカウント/アイデンティティ・エンドポイント仕様ファイルおよび一致するPostmanコレクションを作成できます。

wrapper-api-endpoints-config Hardhatタスクは、デプロイされた契約アーティファクトまたはABIファイルからエンドポイント構成ファイルおよびPostmanコレクションを生成します。Postmanタスクには、ORDS Swagger/OpenAPIドキュメントおよび結合されたAPI定義も組み込むことができます。

前提条件

• プロジェクトの依存関係をインストールし、アーティファクトを使用する予定がある場合はコンパイルします。
• Wrapper APIプラグインとそのタスクがhardhat.config.tsファイルで構成されていることを確認します。
• トークンと、該当する場合はアカウント契約アーティファクトまたはABIファイルを識別します。

エンドポイント構成の生成

事前パッケージ済契約プロジェクトのルート・ディレクトリから次のコマンドを実行します。例のパスと名前をプロジェクト内のパスに置き換えます。

公開する契約ターゲットごとにエンドポイント構成ファイルを生成するには、次のコマンドを実行します。

npx hardhat generate:wrapper-api-endpoints-config \
  --artifact artifacts/contracts/Token.sol/Token.json \
  --out generated/wrapper-api/token-endpoints.json

npx hardhat generate:wrapper-api-endpoints-config \
  --artifact artifacts/contracts/Account.sol/Account.json \
  --out generated/wrapper-api/account-endpoints.json

かわりにABIファイルから開始するには、次の例に示すように、--artifactを--abiに置き換えます。

npx hardhat generate:wrapper-api-endpoints-config \
  --abi ./abi/Token.json \
  --out generated/wrapper-api/token-endpoints.json

生成されたエンドポイント構成を確認してから、ラッパーAPIによって公開されるメソッドおよびパスを選択または調整できるようにします。

Wrapper API Postmanコレクションの生成

次の例に示すように、1つ以上のエンドポイント構成ファイルをカンマ区切り値として渡します。

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/token-endpoints.json,generated/wrapper-api/account-endpoints.json \
  --out generated/wrapper-api/wrapper-api.postman.collection.json

結果のコレクションをPostmanにインポートし、デプロイされたラッパーAPIのURLおよび資格証明を環境変数に移入します。

ORDS Swagger/OpenAPIファイルを含める

オプションの--ords-swagger引数は、ORDS Swagger/OpenAPI JSONファイルを受け入れます。そのGET操作は、生成されたPostmanコレクションのORDS Endpointsフォルダの下に追加され、生成された構成でORDSバック・エンド・オーバーライドとして登録されます。

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/token-endpoints.json,generated/wrapper-api/account-endpoints.json \
  --ords-swagger ./api/ords.swagger.json \
  --out generated/wrapper-api/wrapper-api.postman.collection.json

有効なJSON Swagger/OpenAPIドキュメントを使用してください。このファイルは、このコマンドではデプロイされません。ラッパーAPIおよびPostmanアセットの構築に使用される入力です。

結合APIの定義

結合されたAPIは、1つのPOSTエンドポイントを介して複数の契約メソッドを順番に実行します。まず、エンドポイント構成を生成します。次に、次の例に示すように、その構成にcombinedApisエントリを追加します。

{
  "combinedApis": [
    {
      "name": "createAccountWithRole",
      "path": "createAccountWithRole",
      "httpMethod": "POST",
      "inputs": {
        "required": ["account", "role", "userId"]
      },
      "steps": [
        { "method": "createAccount", "args": ["userId"] },
        { "method": "addRole", "args": ["account", "role"] }
      ],
      "mappings": {
        "createAccount": { "userId": "request.userId" },
        "addRole": {
          "account": "request.account",
          "role": "request.role"
        }
      }
    }
  ]
}

このフラグメントを生成済の構成とマージします。生成されたエンドポイント・コンテンツを置換しないでください。契約の実際のABIメソッド名および引数名を使用します。リクエスト本文は、名前付き入力を最上位フィールドとして提供します(例: account、roleおよびuserId)。ペイロード・ラッパーは使用されません。

すべてのステップは、同じターゲット構成に属している必要があります。APIを組み合せると、トークン・メソッドとアカウントまたはアイデンティティ・メソッドを混在させることはできません。ステップは、書き込まれた順序で実行されます。その動作を考慮して、順序と障害の処理を設計します。次に、次の例に示すように、編集した構成を使用してコレクションを生成します。

npx hardhat generate:wrapper-api-postman-collection \
  --inputs generated/wrapper-api/account-endpoints.json \
  --out generated/wrapper-api/account-wrapper-api.postman.collection.json

トラブルシューティング

条件	解決策
タスクが見つかりませんでした	プロジェクトにラッパーAPIプラグインがインストールされ、hardhat.config.tsファイルで構成されていることを確認します。
アーティファクトまたはABIファイルが見つかりません	--artifactオプションの使用時にプロジェクトをコンパイルするか、--artifactまたは --abiオプションに渡されたパスを修正します。
ORDSエンドポイントがありません	--ords-swaggerパスが有効なJSONを指し、ソースにサポートされているGET操作が含まれていることを確認します。
結合API検証に失敗しました	名前、パス、ステップ、必須入力およびマッピングが存在することを確認します。参照されるすべてのメソッドが同じトークンまたはアカウント/アイデンティティ構成に属していることを確認します。