Importare OpenAPI / Swagger

È l’importazione più completa di Restorm. Sono riconosciute tre versioni: Swagger 2.0, OpenAPI 3.0 e OpenAPI 3.1.

Importare

File ▸ Importa (Ctrl+I), poi un file swagger.json / openapi.json, oppure direttamente l’URL della specifica.

Se l’URL risponde 401 o 403, Restorm propone di collegare un’autenticazione e di riprovare, senza uscire dalla finestra modale di importazione.

Che cosa viene importato

Elemento della specifica	Ciò che Restorm ne fa
servers (oppure host + basePath + schemes)	L’URL di base dell’ambiente, con le variabili di server risolte
tags	Una cartella per etichetta, più una cartella Other per il resto
Ogni operazione	Una richiesta HTTP, metodo e percorso compresi
Parametri	Parametri di percorso, di query e header, tipizzati (stringa, numero, data-ora, enumerazione, segreto…)
requestBody	Il corpo, nel suo tipo di contenuto
examples	Il corpo precompilato con l’esempio fornito
components / definitions	La documentazione di API: modelli, descrizioni
enum	Enumerazioni riutilizzabili come tipo di valore
Risposte	Documentate per tipo di contenuto

I $ref vengono risolti, anche attraverso i componenti.

La riga components / definitions merita di essere sottolineata: l’importazione non si limita alle richieste, conserva tutta la documentazione dell’API — descrizioni, modelli, schemi di sicurezza, esempi, enumerazioni. È consultabile nella scheda Docs della cartella di variabili generata dall’importazione così come in quella di ogni richiesta, e si risincronizza dalla sorgente. Si veda Accesso e aggiornamento della documentazione di un’API importata.

Sicurezza

Gli schemi di sicurezza dichiarati vengono tradotti in header o parametri precablati, con la corrispondente variabile d’ambiente creata automaticamente:

Schema	Ciò che Restorm imposta
apiKey in header o in query	Una coppia denominata come lo schema, valore {{<schema>}}
http + basic	Authorization: Basic {{<schema>_credentials}}
http + bearer, oauth2, openIdConnect	Authorization: Bearer {{<schema>_token}}

Non resta che compilare la variabile — oppure sostituirla con una rotta di autenticazione per beneficiare del rinnovo automatico.

Limiti noti

Le apiKey trasmesse tramite cookie non vengono precablate (OpenAPI 3). Uno schema di sicurezza referenziato ma non dichiarato viene ignorato in silenzio.

Aggiornare

OpenAPI e Swagger figurano tra i formati risincronizzabili: il pulsante Aggiorna della cartella recupera la sorgente e Restorm applica il delta — nuove operazioni aggiunte, operazioni scomparse contrassegnate come deprecate anziché eliminate, modifiche apportate conservate. Si veda Aggiornare dalla sorgente.