Uma das novidades que integram o .NET Core 2.2 (ainda no Preview 3 neste momento – Dezembro/2018) está na possibilidade da realização de testes de APIs REST via linha de comando, empregando, para isso, uma Global Tool chamada HTTP REPL.
O conceito de REPL (read–eval–print loop) como mecanismo para validação e execução de comandos para testes não é novo. Esse tipo de recurso funciona como um language shell, possibilitando o processamento de instruções a partir da digitação de expressões que seguem uma linguagem pré-definida.
No caso específico do HTTP REPL, o pré-requisito para viabilizar a execução de comandos nessa ferramenta está na obrigatoriedade da aplicação a ser testada apresentar o Swagger devidamente configurado. Essa condição/característica traz uma implicação interessante do ponto de vista de Desenvolvimento.
E qual seria a consequência da utilização do Swagger?
Embora parte do pacote de mudanças trazido pelo .NET Core 2.2, o uso do HTTP REPL não está restrito à APIs REST baseadas no ASP.NET Core 2.2.
Em tese, qualquer projeto ajustado para trabalhar em conjunto com o Swagger (mesmo não se tratando de ASP.NET Core) poderá ser testado por meio desta ferramenta.
Voltado para a documentação de APIs, o Swagger utiliza uma padronização conhecida como OpenAPI Specification para detalhar a estrutura e ações possíveis em um projeto baseado no modelo REST.
Para instalar o HTTP REPL, será necessário executar o seguinte comando via PowerShell ou Bash:
dotnet tool install -g --version 2.2.0-* --add-source https://dotnet.myget.org/F/dotnet-core/api/v3/index.json dotnet-httprepl
A instrução dotnet tool list -g exibirá o HTTP REPL instalado, caso o processo de instalação tenha sucesso.
O acesso ao HTTP REPL se dará através da instrução dotnet httprepl:
E também com a instrução dotnet-httprepl (não há diferença prática entre as duas alternativas):
Um ponto a destacar aqui está no fato de que ainda não foi realizada a conexão a nenhum projeto (o status indicado é Disconnected):
Tal conexão acontecerá por meio do comando set base (seguido pela URL do projeto – neste caso, localhost + porta):
Para os testes descritos neste artigo, utilizei uma API REST para conversão de temperaturas e que foi disponibilizada no seguinte repositório no GitHub (este projeto foi construído com o ASP.NET Core 2.1):
Outro aspecto a ressaltar está na indicação de que o JSON de metadados gerado pelo Swagger foi compreendido e serviu de base para a conexão:
A URL indicada corresponde ao endereço gerado automaticamente pelo Swagger com os metadados do projeto:
Podemos a partir daqui navegar entre a estrutura de rotas do projeto, como se estivéssemos em uma árvore de diretórios.
Para isso, temos os comandos dir e ls, que listam os níveis abaixo do qual nos encontramos, assim como o comando cd que permitirá acessar um próximo nível:
Ao atingir o ultimo nível possível, aparecerão também as ações (verbos HTTP) disponíveis, bem como parâmetros esperados:
Neste exemplo específico envolvendo a conversão de temperaturas em Fahrenheit, a instrução get 32 trará em sua resposta uma string JSON contendo os valores equivalentes a 32 graus nesta escala:
Temos ainda um exemplo da conversão de 100 graus Celsius: