Generar una especificación de API de envoltorio y una recopilación de Postman con la línea de comandos

Puede utilizar Blockchain App Builder para crear archivos de especificación de punto final de cuenta/identidad y token filtrados y una recopilación de Postman coincidente.

La tarea Hardhat wrapper-api-endpoints-config genera archivos de configuración de punto final y una recopilación Postman de artefactos de contrato desplegados o archivos ABI. La tarea Postman también puede incorporar un documento de ORDS Swagger/OpenAPI y definiciones de API combinadas.

Requisitos previos

• Instale las dependencias del proyecto y compile si tiene previsto utilizar artefactos.
• Asegúrese de que el plugin de la API de envoltorio y sus tareas estén configurados en el archivo hardhat.config.ts.
• Identifique el token y, cuando corresponda, el artefacto de contrato de cuenta o los archivos ABI.

Generación de una configuración de punto final

Ejecute los siguientes comandos desde el directorio raíz del proyecto de contrato preempaquetado. Sustituya las rutas y los nombres de ejemplo por rutas en el proyecto.

Para generar un archivo de configuración de punto final para cada destino de contrato que desee exponer, ejecute los siguientes comandos.

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

Para empezar desde un archivo ABI en su lugar, sustituya --artifact por --abi, como se muestra en el siguiente ejemplo.

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

Revise la configuración de punto final generada antes que usted, para que pueda seleccionar o acotar los métodos y las rutas que expone la API de envoltorio.

Generar una recopilación de Postman de API de envoltorio

Transfiera uno o más archivos de configuración de punto final como un valor separado por comas, como se muestra en el siguiente ejemplo.

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

Importe la recopilación resultante en Postman y rellene sus variables de entorno con la URL y las credenciales para la API de envoltorio desplegada.

Incluir un archivo ORDS Swagger/OpenAPI

El argumento opcional --ords-swagger acepta un archivo JSON ORDS Swagger/OpenAPI. Sus operaciones GET se agregan en una carpeta ORDS Endpoints de la recopilación de Postman generada y se registran como sustituciones de backend de ORDS en la configuración generada.

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

Utilice un documento de JSON Swagger/OpenAPI válido. Este comando no despliega el archivo; es una entrada que se utiliza para crear los activos de Postman y API de envoltorio.

Definición de una API combinada

Una API combinada ejecuta varios métodos de contrato en secuencia a través de un punto final POST. En primer lugar, genere una configuración de punto final. A continuación, agregue una entrada combinedApis a esa configuración, como se muestra en el siguiente ejemplo.

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

Fusione este fragmento con la configuración generada; no sustituya el contenido de punto final generado. Utilice nombres de método ABI reales y nombres de argumentos del contrato. El cuerpo de la solicitud proporciona las entradas con nombre como campos de nivel superior, por ejemplo: cuenta, rol y userId. No utiliza un envoltorio de carga útil.

Todos los pasos deben pertenecer a la misma configuración de destino. Una API combinada no puede combinar métodos de token con métodos de identidad o cuenta. Los pasos se ejecutan en el orden en que se escriben. Diseñar la secuencia y el manejo de fallos con ese comportamiento en mente. A continuación, genere la recopilación mediante la configuración editada, como se muestra en el siguiente ejemplo.

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

Solución de problemas

Condición	Resolución
No se ha encontrado la Tarea	Compruebe que el proyecto tenga instalado y configurado el plugin de API de envoltorio en el archivo hardhat.config.ts.
No se ha encontrado el artefacto o el archivo ABI	Compile el proyecto al utilizar la opción --artifact o corrija la ruta de acceso transferida a las opciones --artifact o --abi.
Faltan puntos finales ORDS	Verifique que la ruta de acceso --ords-swagger apunta a un JSON válido y que el origen contiene operaciones GET soportadas.
Fallo de validación de API combinada	Asegúrese de que el nombre, la ruta, los pasos, las entradas necesarias y las asignaciones estén presentes. Verifique que todos los métodos a los que se hace referencia pertenecen a la misma configuración de token o cuenta/identidad.