Gerar uma Especificação de API Wrapper e uma Coleção Postman com a Linha de Comando

Você pode usar o Blockchain App Builder para criar arquivos de especificação de ponto final de token e conta/identidade filtrados e uma coleção Postman correspondente.

A tarefa Hardhat do wrapper-api-endpoints-config gera arquivos de configuração de ponto final e uma coleção Postman de artefatos de contrato implantados ou arquivos ABI. A tarefa Postman também pode incorporar um documento ORDS Swagger/OpenAPI e definições de API combinadas.

Pré-requisitos

• Instale as dependências do projeto e compile se você planeja usar artefatos.
• Certifique-se de que o plug-in da API Wrapper e suas tarefas estejam configurados no arquivo hardhat.config.ts.
• Identifique o token e, quando aplicável, o artefato do contrato da conta ou os arquivos ABI.

Gerar uma Configuração de Ponto Final

Execute os comandos a seguir no diretório raiz do projeto do contrato pré-empacotado. Substitua os exemplos de caminhos e nomes por caminhos em seu projeto.

Para gerar um arquivo de configuração de ponto final para cada destino do contrato que você deseja expor, execute os comandos a seguir.

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 começar com um arquivo ABI, substitua --artifact por --abi, conforme mostrado no exemplo a seguir.

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

Revise a configuração de ponto final gerada antes dela, para que você possa escolher ou refinar os métodos e caminhos que são expostos pela API do wrapper.

Gerar uma Coleção Postman da API Wrapper

Informe um ou mais arquivos de configuração de ponto final como um valor separado por vírgulas, conforme mostrado no exemplo a seguir.

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 a coleta resultante para o Postman e preencha suas variáveis de ambiente com o URL e as credenciais da API do wrapper implantada.

Incluir um arquivo ORDS Swagger/OpenAPI

O argumento --ords-swagger opcional aceita um arquivo JSON ORDS Swagger/OpenAPI. Suas operações GET são adicionadas em uma pasta ORDS Endpoints na coleção Postman gerada e são registradas como substituições de back-end do ORDS na configuração gerada.

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

Use um documento JSON Swagger/OpenAPI válido. O arquivo não é implantado por este comando; é uma entrada usada para criar a API wrapper e os ativos Postman.

Definir uma API Combinada

Uma API combinada executa vários métodos de contrato em sequência por meio de um ponto final POST. Primeiro, gere uma configuração de ponto final. Em seguida, adicione uma entrada combinedApis a essa configuração, conforme mostrado no exemplo a seguir.

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

Mescle este fragmento com a configuração gerada; não substitua seu conteúdo de ponto final gerado. Use nomes de método ABI reais e nomes de argumentos do contrato. O corpo da solicitação fornece as entradas nomeadas como campos de nível superior, por exemplo: conta, função e userId. Ele não usa um encapsulador de payload.

Todas as etapas devem pertencer à mesma configuração de destino. Uma API combinada não pode misturar métodos de token com métodos de conta ou identidade. As etapas são executadas na ordem em que foram gravadas. Projete a sequência e o tratamento de falhas com esse comportamento em mente. Em seguida, gere a coleção usando a configuração editada, conforme mostrado no exemplo a seguir.

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

Solucionando Problemas

Condição	Resolução
Tarefa não encontrada	Verifique se o projeto tem o plug-in de API wrapper instalado e configurado no arquivo hardhat.config.ts.
Artefato ou arquivo ABI não encontrado	Compile o projeto ao usar a opção --artifact ou corrija o caminho passado para as opções --artifact ou --abi.
Pontos finais ORDS ausentes	Verifique se o caminho --ords-swagger aponta para um JSON válido e se a origem contém operações GET suportadas.
Falha na validação da API combinada	Verifique se o nome, o caminho, as etapas, as entradas obrigatórias e os mapeamentos estão presentes. Verifique se todos os métodos referenciados pertencem à mesma configuração de token ou conta/identidade.