Detetar problemas numa API importada

Quando importa uma API (OpenAPI, Swagger e os restantes formatos suportados), o Restorm mantém a documentação estruturada da API na respetiva pasta de variáveis. Logo após a importação — e sempre que reabre o ficheiro — o Restorm projeta discretamente essa documentação num design e executa a mesma validação que o designer de API aplica, inteiramente em segundo plano. Nunca bloqueia a importação nem interfere com aquilo que está a fazer.

Se não encontrar nada, não vê nada. Se encontrar problemas estruturais, indica-os em dois locais.

O «!» na barra lateral

A pasta de variáveis que contém a API sinalizada mostra um pequeno «!» à direita da respetiva linha. É o sinal de relance de que o design desta API tem algo que merece atenção — e desaparece por si só assim que a API volta a estar limpa (após uma nova importação ou uma atualização da API que a corrija).

O separador «Problemas»

Abra a pasta de variáveis e esta ganha um separador Problemas. O separador só aparece quando foram detetados problemas — uma API limpa nunca o mostra.

O separador Problemas da pasta de variáveis de uma API importada: um aviso, seguido dos problemas agrupados por tipo — «Várias rotas respondem ao mesmo método e caminho», «Algumas rotas não declaram qualquer resposta», «Algumas rotas situam-se num caminho reservado pelo servidor de design» — cada um listando as rotas exatas que afeta, uma delas expandida para mostrar a documentação dessa rota

Os problemas são agrupados por tipo, de modo que vinte rotas duplicadas se leem como uma única linha com uma contagem, em vez de vinte entradas separadas. Sob cada tipo, o Restorm lista as entidades exatas em causa — uma rota mostra o seu verbo HTTP e o caminho real, e expande-se até à documentação dessa rota, para que possa ver o que declara sem sair do separador.

As verificações espelham as do designer de API, pelo que os tipos de problemas que poderá ver incluem:

rotas duplicadas — duas rotas que respondem ao mesmo método e caminho;
respostas em falta — uma rota que não declara qualquer resposta;
caminhos reservados — uma rota situada num caminho reservado pelo Mock Server (/swagger.json, /graphql, …), que nunca responderia;
problemas de restrição — um padrão inválido, ou um mínimo superior ao seu máximo.

A lista é apenas de leitura: indica-lhe o que corrigir, e a correção faz-se na origem (reimporte uma especificação corrigida ou edite a API). É recalculada nos eventos que alteram uma API — a abertura de um ficheiro, uma importação, uma atualização da API — e não a cada tecla premida.