Acesso e atualização da documentação de uma API importada

Quando importa uma especificação, o Restorm não cria apenas pedidos: conserva a documentação da API — descrições, modelos, esquemas de segurança, exemplos, enumerações — e anexa-a à pasta de variáveis criada pela importação.

Aceder à documentação

O separador Docs da pasta de variáveis

É a vista principal. Abra a pasta de variáveis resultante da importação: a sua barra de subseparadores inclui um separador Docs, ao lado de Ambientes, Variáveis personalizadas e Notas.

O separador só aparece se a pasta provier de uma importação — uma pasta de variáveis que criou à mão não tem documentação para mostrar.

Os outros acessos

A partir de	O que obtém
O separador Docs de um pedido	A documentação apenas dessa operação — sem índice nem bloco de informações gerais. Só aparece se a operação for encontrada na especificação
O separador Docs de uma pasta simples	A documentação restrita às operações que essa pasta contém
O subseparador inicial da pasta de variáveis	O cartão Ver a documentação — “Percorra a documentação da API, os modelos e os endpoints”
O ecrã inicial (cartão API)	A ligação rápida Documentação
O motor de busca da barra de título	Uma pré-visualização da documentação ao passar o cursor sobre um resultado

O que a vista contém

De cima para baixo:

• o título da API e a sua descrição;
• um bloco de informações: Version, Source format (com uma ligação para o URL de origem), Server (esquemas, anfitrião, caminho de base), Contact, License, Terms of service, External docs;
• uma secção por etiqueta, com a respetiva descrição;
• um bloco por operação: método e URL, resumo, marcador de grupo, distintivo deprecated quando aplicável, secção Security (tipo de esquema, fluxos OAuth 2, âmbitos) e um Example payload recolhível;
• as tabelas Parameters e Responses (os códigos de estado são coloridos);
• Models — um grafo interativo dos esquemas, navegável e com zoom;
• Polymorphism — as composições oneOf / anyOf / allOf;
• Enums — as enumerações, fundidas com as da pasta.

Note

Os títulos destas secções (Models, Enums, Parameters, Responses, Security, Example payload) são apresentados em inglês em todos os idiomas da aplicação. São aqui reproduzidos tal e qual para que os reconheça no ecrã.

Criar um pedido a partir da documentação

Cada bloco de operação tem um botão + Add que cria um pedido previamente configurado para essa operação. É o caminho mais curto quando uma importação foi parcial, ou quando uma operação acabou de surgir na especificação.

Navegar e pesquisar

Um índice está fixado à direita — secções Overview, Operations, Models, Enums — recolhível e redimensionável. Clicar num modelo desloca a página até ao grafo e centra nele o nó correspondente.

Atalho	Efeito
Ctrl+F / Cmd+F	Abre a pesquisa na documentação
F3 / Enter	Correspondência seguinte
Shift+F3 / Shift+Enter	Correspondência anterior
Esc	Fecha a pesquisa

Um contador indica a posição nos resultados.

Atualizar a documentação

Uma especificação evolui. O Restorm sabe ir buscar a origem e aplicar o delta — documentação e pedidos — sem apagar o seu trabalho.

Apenas para as importações por URL

A ressincronização só está disponível se a pasta tiver sido importada a partir de um URL. Uma importação a partir de um ficheiro ou por colagem não registou nenhuma origem, e o botão de atualização não aparece: o subseparador inicial mostra então “Esta pasta não foi criada a partir de uma origem importável.”

Este URL não é alterável depois na interface. Para mudar de origem, faça uma nova importação.

Onde está o botão

Duas entradas, equivalentes:

1. o subseparador inicial da pasta de variáveis, secção Atualizações da spec — mostra o URL, a Última importação e a Última verificação, e inclui o botão Atualizar;
2. o clique com o botão direito na pasta na árvore lateral → Atualizar.

Não existe verificação automática

O Restorm não vigia as suas especificações em segundo plano e não o avisará de que está disponível uma nova versão. A verificação é sempre desencadeada por você.

O que acontece

1. Aparece uma janela “A atualizar a spec…” durante a obtenção. As {{variables}} do URL e dos cabeçalhos são resolvidas, e a rota de autenticação anexada é executada previamente.
2. O Restorm compara uma impressão digital da origem obtida com a que foi registada na última importação.
3. Nada mudou → “A spec da API está atualizada.”, e está terminado.
4. Algo mudou (ou a obtenção falhou) → abre-se o assistente de ressincronização.

O assistente

• O URL de origem é mostrado em modo de leitura.
• Um marcador permite anexar, alterar ou desanexar uma rota de autenticação, e um submenu Custom headers permite adicionar cabeçalhos fixos reenviados em cada atualização.
• Dois separadores de pré-visualização:
  • Routes — a árvore das operações encontradas na nova versão, com filtro e seleção. As operações já presentes na sua pasta estão bloqueadas e sempre assinaladas; escolhe apenas quais das novas adicionar;
  • Documentation — a documentação da nova versão, em modo de leitura, antes de validar.
• O botão de validação mostra o número de operações novas selecionadas, por exemplo Apply update (3).

Note

O assistente é hoje apresentado em inglês qualquer que seja o idioma da aplicação (“Refresh from source”, “Apply update”, separadores “Routes” e “Documentation”). Os títulos ingleses são, por isso, aqui reproduzidos tal e qual.

O que é alterado, e o que não é

É este o ponto importante: a especificação manda no que descreve, você manda no resto.

Elemento	Comportamento
Nome de um pedido	Nunca alterado
Método e URL	Nunca alterados
Parâmetros, cabeçalhos e parâmetros de caminho existentes	Conservados tal e qual — valor, descrição, ativação
Parâmetros adicionados pela especificação	Adicionados, com o valor predefinido da especificação ou vazios
Parâmetros retirados da especificação	Conservados no pedido
Operação nova	Adicionada onde uma importação nova a teria colocado (incluindo a pasta de etiqueta)
Operação marcada como obsoleta pela especificação	Sinalizada; aparece esmaecida na árvore
Operação desaparecida da especificação	Sinalizada como retirada; aparece rasurada na árvore, continua executável e nunca é eliminada
Documentação de API e enumerações	Substituídas na íntegra pela nova versão — é isso que atualiza o separador Docs

Nada é nunca eliminado da sua árvore: uma operação que desaparece da origem é marcada, não apagada.

Se a origem exigir autenticação

Uma resposta 401 ou 403 abre o assistente com a mensagem de erro apresentada tal e qual (por exemplo HTTP 401: Unauthorized). Anexe uma rota de autenticação ou adicione cabeçalhos fixos, e a pré-visualização é relançada.

Formatos ressincronizáveis

Doze formatos dispõem de ressincronização: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC e Smithy.

Para todos os outros, uma nova importação cria uma nova árvore. A lista completa está em Atualizar a partir da origem.