使用命令行產生包裝函式 API 規格與 Postman Collection

您可以使用區塊鏈 App 產生器來建立篩選的權杖和帳戶 / 識別端點規格檔案，以及相符的 Postman 集合。

wrapper-api-endpoints-config Hardhat 工作會從已部署的合約物件或 ABI 檔案產生端點組態檔和 Postman 集合。Postman 工作也可以結合 ORDS Swagger/OpenAPI 文件和結合的 API 定義。

先決條件

• 如果您計畫使用使用者自建物件，請安裝專案的相依性並進行編譯。
• 請確定已在 hardhat.config.ts 檔案中設定「包裝程式 API」Plug-in 及其工作。
• 識別權杖，並在適用的情況下，識別帳戶合約構件或 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 顯示的方法和路徑。

產生包裝函式 API Postman Collection

傳送一或多個端點組態檔作為逗號分隔值，如下列範例所示。

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 會依序透過一個 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

疑難排解

條件	解決方式
找不到工作	檢查專案是否已安裝並設定 hardhat.config.ts 檔案中的包裝函式 API Plug-in。
找不到構件或 ABI 檔案	使用 --artifact 選項時編譯專案，或更正傳送至 --artifact 或 --abi 選項的路徑。
遺漏 ORDS 端點	請檢查 --ords-swagger 路徑是否指向有效的 JSON，以及來源是否包含支援的 GET 作業。
合併的 API 驗證失敗	確定名稱、路徑、步驟、必要的輸入值以及對應存在。確定所有參照的方法都屬於相同的記號或帳戶 / 識別組態。