Accesso e aggiornamento della documentazione di un’API importata

Quando si importa una specifica, Restorm non crea soltanto delle richieste: conserva la documentazione dell’API — descrizioni, modelli, schemi di sicurezza, esempi, enumerazioni — e la allega alla cartella di variabili creata dall’importazione.

Accedere alla documentazione

La scheda Docs della cartella di variabili

È la vista principale. Aprendo la cartella di variabili generata dall’importazione, la sua barra di sotto-schede porta una scheda Docs, accanto a Ambienti, Variabili personalizzate e Note.

La scheda compare solo se la cartella proviene da un’importazione — una cartella di variabili creata a mano non ha documentazione da mostrare.

Gli altri accessi

Da	Che cosa si ottiene
La scheda Docs di una richiesta	La documentazione di quella sola operazione — senza sommario né blocco di informazioni generali. Compare solo se l’operazione viene ritrovata nella specifica
La scheda Docs di una cartella semplice	La documentazione limitata alle operazioni contenute in quella cartella
La sotto-scheda iniziale della cartella di variabili	La scheda Vedi la documentazione — «Sfoglia la documentazione dell’API, i modelli e gli endpoint»
La schermata di benvenuto (scheda API)	Il collegamento rapido Documentazione
Il motore di ricerca della barra del titolo	Un’anteprima della documentazione passando il puntatore su un risultato

Che cosa contiene la vista

Dall’alto verso il basso:

• il titolo dell’API e la sua descrizione;
• un blocco di informazioni: Version, Source format (con un collegamento all’URL di origine), Server (schemi, host, percorso di base), Contact, License, Terms of service, External docs;
• una sezione per etichetta, con la sua descrizione;
• un blocco per operazione: metodo e URL, riepilogo, pastiglia di gruppo, badge deprecated se applicabile, sezione Security (tipo di schema, flusso OAuth 2, scope) e un Example payload richiudibile;
• le tabelle Parameters e Responses (i codici di stato sono colorati);
• Models — un grafo interattivo degli schemi, navigabile e zoomabile;
• Polymorphism — le composizioni oneOf / anyOf / allOf;
• Enums — le enumerazioni, fuse con quelle della cartella.

Note

Le diciture di queste sezioni (Models, Enums, Parameters, Responses, Security, Example payload) sono mostrate in inglese in tutte le lingue dell’applicazione. Vengono riportate così come sono anche qui, per poterle ritrovare a schermo.

Creare una richiesta dalla documentazione

Ogni blocco di operazione porta un pulsante + Add che crea una richiesta preconfigurata per quell’operazione. È la via più breve quando un’importazione è stata parziale, oppure quando un’operazione è appena comparsa nella specifica.

Navigare e cercare

Un sommario è ancorato a destra — sezioni Overview, Operations, Models, Enums — richiudibile e ridimensionabile. Facendo clic su un modello si scorre fino al grafo e vi si centra il nodo corrispondente.

Scorciatoia	Effetto
Ctrl+F / Cmd+F	Apre la ricerca nella documentazione
F3 / Enter	Corrispondenza successiva
Shift+F3 / Shift+Enter	Corrispondenza precedente
Esc	Chiude la ricerca

Un contatore indica la posizione all’interno dei risultati.

Aggiornare la documentazione

Una specifica evolve. Restorm sa andare a recuperare la sorgente e applicare il delta — documentazione e richieste — senza sovrascrivere il lavoro svolto.

Soltanto per le importazioni tramite URL

La risincronizzazione è disponibile solo se la cartella è stata importata da un URL. Un’importazione da file o per incollaggio non registra alcuna sorgente, e il pulsante di aggiornamento non compare: la sotto-scheda iniziale mostra allora «Questa cartella non è stata creata da una sorgente importabile.»

Questo URL non è modificabile a posteriori nell’interfaccia. Per cambiare sorgente occorre rifare un’importazione.

Dov’è il pulsante

Due punti d’ingresso, equivalenti:

1. la sotto-scheda iniziale della cartella di variabili, sezione Aggiornamenti della spec — mostra l’URL, l’Ultima importazione e l’Ultima verifica, e porta il pulsante Aggiorna;
2. il clic destro sulla cartella nell’albero laterale → Aggiorna.

Non esiste una verifica automatica

Restorm non monitora le specifiche in background e non avvisa che è disponibile una nuova versione. La verifica è sempre avviata dall’utente.

Che cosa succede

1. Durante il recupero compare una finestra «Aggiornamento della spec…». Le {{variables}} dell’URL e degli header vengono risolte e la rotta di autenticazione collegata viene eseguita in via preliminare.
2. Restorm confronta un’impronta della sorgente recuperata con quella registrata all’ultima importazione.
3. Nulla è cambiato → «La spec dell’API è aggiornata.», ed è tutto.
4. Qualcosa è cambiato (oppure il recupero è fallito) → si apre la procedura guidata di risincronizzazione.

La procedura guidata

• L’URL di origine è mostrato in sola lettura.
• Una pastiglia permette di collegare, modificare o scollegare una rotta di autenticazione, e un sottomenu Custom headers di aggiungere header fissi rieseguiti a ogni aggiornamento.
• Due schede di anteprima:
  • Routes — l’albero delle operazioni trovate nella nuova versione, con filtro e selezione. Le operazioni già presenti nella cartella sono bloccate e sempre selezionate; si scelgono soltanto quali delle nuove aggiungere;
  • Documentation — la documentazione della nuova versione, in sola lettura, prima di confermare.
• Il pulsante di conferma mostra il numero di nuove operazioni selezionate, per esempio Apply update (3).

Note

La procedura guidata è oggi mostrata in inglese qualunque sia la lingua dell’applicazione («Refresh from source», «Apply update», schede «Routes» e «Documentation»). Le diciture inglesi vengono quindi riportate qui così come sono.

Che cosa viene modificato e che cosa no

È il punto importante: la specifica fa fede su ciò che descrive, l’utente fa fede sul resto.

Elemento	Comportamento
Nome di una richiesta	Mai modificato
Metodo e URL	Mai modificati
Parametri, header e parametri di percorso esistenti	Conservati così come sono — valore, descrizione, attivazione
Parametri aggiunti dalla specifica	Aggiunti, con il valore predefinito della specifica o vuoti
Parametri rimossi dalla specifica	Conservati nella richiesta
Operazione nuova	Aggiunta nel punto in cui l’avrebbe collocata una nuova importazione (cartella di etichetta compresa)
Operazione contrassegnata come deprecata dalla specifica	Segnalata; compare attenuata nell’albero
Operazione scomparsa dalla specifica	Segnalata come rimossa; compare barrata nell’albero, resta eseguibile e non viene mai eliminata
Documentazione di API ed enumerazioni	Sostituite integralmente dalla nuova versione — è ciò che aggiorna la scheda Docs

Nulla viene mai eliminato dall’albero: un’operazione che scompare dalla sorgente viene contrassegnata, non cancellata.

Se la sorgente richiede un’autenticazione

Una risposta 401 o 403 apre la procedura guidata con il messaggio di errore mostrato così com’è (per esempio HTTP 401: Unauthorized). Basta collegare una rotta di autenticazione o aggiungere header fissi, e l’anteprima viene rilanciata.

Formati risincronizzabili

Dodici formati dispongono della risincronizzazione: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC e Smithy.

Per tutti gli altri, una nuova importazione crea un nuovo albero. L’elenco completo è in Aggiornare dalla sorgente.