Wrapper-API-Spezifikation und Postman-Sammlung mit der Befehlszeile generieren

Mit Blockchain App Builder können Sie gefilterte Token- und Account-/Identitätsendpunktspezifikationsdateien sowie eine übereinstimmende Postman-Sammlung erstellen.

Mit der Hardhat-Aufgabe wrapper-api-endpoints-config werden Endpunktkonfigurationsdateien und eine Postman-Collection aus bereitgestellten Vertragsartefakten oder ABI-Dateien generiert. Die Postman-Aufgabe kann auch ein ORDS-Swagger/OpenAPI-Dokument und kombinierte API-Definitionen enthalten.

Voraussetzungen

• Installieren Sie die Abhängigkeiten des Projekts, und kompilieren Sie sie, wenn Sie Artefakte verwenden möchten.
• Stellen Sie sicher, dass das Wrapper-API-Plug-in und die zugehörigen Aufgaben in der Datei hardhat.config.ts konfiguriert sind.
• Identifizieren Sie das Token und gegebenenfalls das Accountvertragsartefakt oder die ABI-Dateien.

Endpunktkonfiguration generieren

Führen Sie die folgenden Befehle aus dem Root-Verzeichnis des vordefinierten Vertragsprojekts aus. Ersetzen Sie die Beispielpfade und -namen durch Pfade in Ihrem Projekt.

Um eine Endpunktkonfigurationsdatei für jedes Vertragsziel zu generieren, das Sie bereitstellen möchten, führen Sie die folgenden Befehle aus.

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

Um stattdessen mit einer ABI-Datei zu beginnen, ersetzen Sie --artifact durch --abi, wie im folgenden Beispiel gezeigt.

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

Prüfen Sie die generierte Endpunktkonfiguration, bevor Sie sie verwenden, damit Sie die Methoden und Pfade auswählen oder verfeinern können, die von der Wrapper-API bereitgestellt werden.

Postman-Sammlung für Wrapper-API generieren

Übergeben Sie eine oder mehrere Endpunktkonfigurationsdateien als durch Komma getrennten Wert, wie im folgenden Beispiel dargestellt.

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

Importieren Sie die resultierende Collection in Postman, und füllen Sie die Umgebungsvariablen mit der URL und den Zugangsdaten für die bereitgestellte Wrapper-API.

ORDS-Swagger-/OpenAPI-Datei einschließen

Das optionale Argument --ords-swagger akzeptiert eine ORDS-Swagger-/OpenAPI-JSON-Datei. Die GET-Vorgänge werden unter einem Ordner ORDS Endpoints in der generierten Postman-Collection hinzugefügt und als ORDS-Backend-Overrides in der generierten Konfiguration registriert.

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

Verwenden Sie ein gültiges JSON-Swagger-/OpenAPI-Dokument. Die Datei wird nicht von diesem Befehl bereitgestellt. Sie ist eine Eingabe, mit der die Wrapper-API und Postman-Assets erstellt werden.

Kombinierte API definieren

Eine kombinierte API führt mehrere Vertragsmethoden nacheinander über einen POST-Endpunkt aus. Erstellen Sie zunächst eine Endpunktkonfiguration. Fügen Sie dann einen combinedApis-Eintrag zu dieser Konfiguration hinzu, wie im folgenden Beispiel gezeigt.

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

Dieses Fragment mit der generierten Konfiguration zusammenführen; den generierten Endpunktinhalt nicht ersetzen. Verwenden Sie tatsächliche ABI-Methodennamen und Argumentnamen aus Ihrem Vertrag. Der Anforderungstext stellt die benannten Eingaben als Felder der obersten Ebene bereit. Beispiel: "account", "role" und "userId". Es wird kein Payload Wrapper verwendet.

Alle Schritte müssen zur selben Zielkonfiguration gehören. Eine kombinierte API kann Tokenmethoden nicht mit Account- oder Identitätsmethoden kombinieren. Die Schritte werden in der Reihenfolge ihrer Schreibweise ausgeführt. Entwerfen Sie die Sequenz und die Fehlerbehandlung unter Berücksichtigung dieses Verhaltens. Generieren Sie dann die Collection mit der bearbeiteten Konfiguration, wie im folgenden Beispiel gezeigt.

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

Fehlerbehebung

Bedingung	Lösung
Aufgabe wurde nicht gefunden	Prüfen Sie, ob das Wrapper-API-Plug-in für das Projekt in der Datei hardhat.config.ts installiert und konfiguriert ist.
Artefakt- oder ABI-Datei nicht gefunden	Kompilieren Sie das Projekt mit der Option --artifact, oder korrigieren Sie den Pfad, der an die Optionen --artifact oder --abi übergeben wird.
ORDS-Endpunkte fehlen	Prüfen Sie, ob der Pfad --ords-swagger auf gültige JSON verweist und ob die Quelle unterstützte GET-Vorgänge enthält.
Kombinierte API-Validierung nicht erfolgreich	Stellen Sie sicher, dass Name, Pfad, Schritte, erforderliche Eingaben und Mappings vorhanden sind. Prüfen Sie, ob alle referenzierten Methoden zu derselben Token- oder Account-/Identitätskonfiguration gehören.