Importar OpenAPI / Swagger
É a importação mais completa do Restorm. São reconhecidas três versões: Swagger 2.0, OpenAPI 3.0 e OpenAPI 3.1.
Importar
Section titled “Importar”Ficheiro ▸ Importar (Ctrl+I) e depois um ficheiro swagger.json /
openapi.json, ou diretamente o URL da especificação.
Se o URL responder 401 ou 403, o Restorm propõe-lhe anexar uma autenticação e
tentar de novo, sem sair da janela de importação.
O que é importado
Section titled “O que é importado”| Elemento da especificação | O que o Restorm faz com ele |
|---|---|
servers (ou host + basePath + schemes) | O URL de base do ambiente, com as variáveis de servidor resolvidas |
tags | Uma pasta por etiqueta, mais uma pasta Other para o resto |
| Cada operação | Um pedido HTTP, incluindo método e caminho |
| Parâmetros | Parâmetros de caminho, de consulta e cabeçalhos, tipados (cadeia, número, data-hora, enumeração, segredo…) |
requestBody | O corpo, no respetivo tipo de conteúdo |
examples | O corpo pré-preenchido com o exemplo fornecido |
components / definitions | A documentação de API: modelos, descrições |
enum | Enumerações reutilizáveis como tipo de valor |
| Respostas | Documentadas por tipo de conteúdo |
Os $ref são resolvidos, incluindo através dos componentes.
A linha components / definitions merece destaque: a importação não se limita
aos pedidos, conserva toda a documentação da API — descrições, modelos,
esquemas de segurança, exemplos, enumerações. Pode ser consultada no separador
Docs da pasta de variáveis resultante da importação e também no de cada
pedido, e ressincroniza-se a partir da origem. Consulte
Acesso e atualização da documentação de uma API importada.
Segurança
Section titled “Segurança”Os esquemas de segurança declarados são traduzidos em cabeçalhos ou parâmetros já preparados, com a variável de ambiente correspondente criada para si:
| Esquema | O que o Restorm coloca |
|---|---|
apiKey em cabeçalho ou em consulta | Um par com o nome do esquema, valor {{<schema>}} |
http + basic | Authorization: Basic {{<schema>_credentials}} |
http + bearer, oauth2, openIdConnect | Authorization: Bearer {{<schema>_token}} |
Resta apenas preencher a variável — ou substituí-la por uma rota de autenticação para beneficiar da renovação automática.
Atualizar
Section titled “Atualizar”O OpenAPI e o Swagger figuram entre os formatos ressincronizáveis: o botão Atualizar da pasta obtém a origem e o Restorm aplica o delta — novas operações adicionadas, operações desaparecidas marcadas como obsoletas em vez de eliminadas, as suas alterações conservadas. Consulte Atualizar a partir da origem.