Genera una specifica API wrapper e una raccolta postman con la riga di comando

È possibile utilizzare Blockchain App Builder per creare file di specifica degli endpoint di token e account/identità filtrati e una raccolta Postman corrispondente.

Il task Hardhat wrapper-api-endpoints-config genera i file di configurazione degli endpoint e una raccolta Postman dagli artifact del contratto distribuiti o dai file ABI. Il task Postman può anche incorporare un documento ORDS Swagger/OpenAPI e definizioni API combinate.

Prerequisiti

• Installare le dipendenze del progetto e compilare se si prevede di utilizzare gli artifact.
• Assicurarsi che il plugin API wrapper e i relativi task siano configurati nel file hardhat.config.ts.
• Identificare il token e, se applicabile, l'artifact del contratto conto o i file ABI.

Generare una configurazione endpoint

Eseguire i comandi seguenti dalla directory principale del progetto di contratto preconfezionato. Sostituire i percorsi e i nomi di esempio con i percorsi nel progetto.

Per generare un file di configurazione dell'endpoint per ogni destinazione contratto che si desidera esporre, eseguire i comandi riportati di seguito.

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

Per iniziare da un file ABI, sostituire --artifact con --abi, come mostrato nell'esempio seguente.

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

Rivedere prima la configurazione dell'endpoint generato, in modo da poter scegliere o perfezionare i metodi e i percorsi esposti dall'API wrapper.

Genera raccolta postman API wrapper

Passare uno o più file di configurazione degli endpoint come valore separato da virgole, come mostrato nell'esempio riportato di seguito.

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

Importare la raccolta risultante in Postman e popolare le relative variabili di ambiente con l'URL e le credenziali per l'API wrapper distribuita.

Includi un file ORDS Swagger/OpenAPI

L'argomento --ords-swagger facoltativo accetta un file JSON Swagger/OpenAPI ORDS. Le operazioni GET vengono aggiunte sotto una cartella ORDS Endpoints nella raccolta Postman generata e vengono registrate come sostituzioni back-end ORDS nella configurazione generata.

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

Utilizzare un documento Swagger/OpenAPI JSON valido. Il file non è distribuito da questo comando; è un input utilizzato per creare l'API wrapper e gli asset Postman.

Definisce un'API combinata

Un'API combinata esegue diversi metodi di contratto in sequenza attraverso un endpoint POST. Generare innanzitutto una configurazione dell'endpoint. Quindi , aggiungere una voce combinedApis a tale configurazione, come mostrato nell'esempio seguente.

{
  "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"
        }
      }
    }
  ]
}

Unisci questo frammento alla configurazione generata; non sostituire il contenuto dell'endpoint generato. Utilizzare i nomi dei metodi ABI effettivi e i nomi degli argomenti del contratto. Il corpo della richiesta fornisce gli input denominati come campi di livello superiore, ad esempio account, ruolo e userId. Non utilizza un wrapper del payload.

Tutti i passi devono appartenere alla stessa configurazione di destinazione. Un'API combinata non può combinare metodi token con metodi account o identità. I passi vengono eseguiti nell'ordine in cui sono scritti. Progettare la sequenza e la gestione dei guasti con questo comportamento in mente. Generare quindi la raccolta utilizzando la configurazione modificata, come mostrato nell'esempio riportato di seguito.

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

Risoluzione dei problemi

Condizione	Risoluzione
Task non trovata	Verificare che nel progetto sia installato e configurato il plugin API wrapper nel file hardhat.config.ts.
File artifact o ABI non trovato	Compilare il progetto quando si utilizza l'opzione --artifact oppure correggere il percorso passato alle opzioni --artifact o --abi.
Endpoint ORDS mancanti	Verificare che il percorso --ords-swagger punti a un JSON valido e che l'origine contenga operazioni GET supportate.
Convalida API combinata non riuscita	Assicurarsi che il nome, il percorso, i passi, gli input richiesti e i mapping siano presenti. Verificare che tutti i metodi di riferimento appartengano alla stessa configurazione di token o account/identità.