Générer une spécification d'API Wrapper et une collection Postman avec la ligne de commande

Vous pouvez utiliser Blockchain App Builder pour créer des fichiers filtrés de spécification d'adresse de compte/d'identité et une collection Postman correspondante.

La tâche wrapper-api-endpoints-config Hardhat génère des fichiers de configuration d'adresse et une collection Postman à partir d'artefacts de contrat déployés ou de fichiers ABI. La tâche Postman peut également intégrer un document ORDS Swagger/OpenAPI et des définitions d'API combinées.

Prérequis

• Installez les dépendances du projet et compilez-les si vous prévoyez d'utiliser des artefacts.
• Assurez-vous que le module d'extension d'API Wrapper et ses tâches sont configurés dans le fichier hardhat.config.ts.
• Identifiez le jeton et, le cas échéant, les fichiers ABI ou d'artefact de contrat de compte.

Générer une configuration d'adresse

Exécutez les commandes suivantes à partir du répertoire racine du projet de contrat préemballé. Remplacez les exemples de chemins et de noms par des chemins dans votre projet.

Pour générer un fichier de configuration d'adresse pour chaque cible de contrat à exposer, exécutez les commandes suivantes.

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

Pour commencer à partir d'un fichier ABI, remplacez --artifact par --abi, comme indiqué dans l'exemple suivant.

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

Passez en revue la configuration d'adresse générée avant vous afin de pouvoir choisir ou affiner les méthodes et les chemins exposés par l'API de wrapper.

Générer une collection Postman d'API Wrapper

Transmettez un ou plusieurs fichiers de configuration d'adresse sous forme de valeur séparée par des virgules, comme indiqué dans l'exemple suivant.

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

Importez la collection résultante dans Postman et renseignez ses variables d'environnement avec l'URL et les informations d'identification de l'API de wrapper déployée.

Inclure un fichier ORDS Swagger/OpenAPI

L'argument facultatif --ords-swagger accepte un fichier JSON ORDS Swagger/OpenAPI. Ses opérations GET sont ajoutées sous un dossier ORDS Endpoints dans la collection Postman générée et sont enregistrées en tant que remplacements de back-end ORDS dans la configuration générée.

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

Utilisez un document Swagger/OpenAPI JSON valide. Le fichier n'est pas déployé par cette commande ; il s'agit d'une entrée utilisée pour créer l'API de wrapper et les ressources Postman.

Définir une API combinée

Une API combinée exécute plusieurs méthodes de contrat en séquence via une adresse POST. Commencez par générer une configuration d'adresse. Ajoutez ensuite une entrée combinedApis à cette configuration, comme indiqué dans l'exemple suivant.

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

Fusionnez ce fragment avec la configuration générée ; ne remplacez pas le contenu d'adresse généré. Utilisez les noms réels de méthode ABI et les noms d'argument de votre contrat. Le corps de la demande fournit les entrées nommées en tant que champs de niveau supérieur, par exemple Compte, Rôle et ID utilisateur. Il n'utilise pas de wrapper de charge utile.

Toutes les étapes doivent appartenir à la même configuration cible. Une API combinée ne peut pas mélanger des méthodes de jeton avec des méthodes de compte ou d'identité. Les étapes sont exécutées dans l'ordre dans lequel elles sont écrites. Concevez la séquence et la gestion des échecs en gardant ce comportement à l'esprit. Générez ensuite la collection à l'aide de la configuration modifiée, comme indiqué dans l'exemple suivant.

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

Dépannage

Condition	Résolution
Tâche non trouvée	Vérifiez que le module d'extension d'API de wrapper du projet est installé et configuré dans le fichier hardhat.config.ts.
Fichier d'artefact ou ABI introuvable	Compilez le projet lorsque vous utilisez l'option --artifact ou corrigez le chemin transmis aux options --artifact ou --abi.
Les adresses ORDS sont manquantes	Vérifiez que le chemin --ords-swagger pointe vers un fichier JSON valide et que la source contient des opérations GET prises en charge.
Echec de la validation de l'API combinée	Assurez-vous que le nom, le chemin, les étapes, les entrées requises et les mappings sont présents. Vérifiez que toutes les méthodes référencées appartiennent à la même configuration de jeton ou de compte/identité.