Accesul și actualizarea documentației unui API importat

Când importați o specificație, Restorm nu creează doar cereri: el păstrează documentația API-ului — descrieri, modele, scheme de securitate, exemple, enumerări — și o atașează folderului de variabile creat de import.

Accesul la documentație

Fila Docs a folderului de variabile

Aceasta este vizualizarea principală. Deschideți folderul de variabile provenit din import: bara sa de subfile poartă o filă Docs, alături de Medii, Variabile personalizate și Notițe.

Fila apare numai dacă folderul provine dintr-un import — un folder de variabile pe care l-ați creat manual nu are documentație de afișat.

Celelalte căi de acces

De unde	Ce obțineți
Fila Docs a unei cereri	Documentația acelei singure operații — fără cuprins și fără blocul de informații generale. Apare numai dacă operația este regăsită în specificație
Fila Docs a unui folder simplu	Documentația restrânsă la operațiile pe care le conține acel folder
Subfila de întâmpinare a folderului de variabile	Cardul Vezi documentația — „Parcurgeți documentația API-ului, modelele și endpointurile”
Ecranul de bun venit (cardul API)	Linkul rapid Documentație
Motorul de căutare din bara de titlu	O previzualizare a documentației la trecerea cursorului peste un rezultat

Ce conține vizualizarea

De sus în jos:

• titlul API-ului și descrierea sa;
• un bloc de informații: Version, Source format (cu un link către URL-ul sursă), Server (scheme, gazdă, cale de bază), Contact, License, Terms of service, External docs;
• o secțiune pentru fiecare etichetă, cu descrierea sa;
• un bloc pentru fiecare operație: metodă și URL, rezumat, pastilă de grup, insigna deprecated dacă este cazul, secțiunea Security (tipul schemei, fluxuri OAuth 2, domenii) și un Example payload pliabil;
• tabelele Parameters și Responses (codurile de stare sunt colorate);
• Models — un graf interactiv al schemelor, navigabil și cu zoom;
• Polymorphism — compunerile oneOf / anyOf / allOf;
• Enums — enumerările, contopite cu cele ale folderului.

Note

Denumirile acestor secțiuni (Models, Enums, Parameters, Responses, Security, Example payload) sunt afișate în engleză în toate limbile aplicației. Sunt reluate aici ca atare, pentru a le regăsi pe ecran.

Crearea unei cereri din documentație

Fiecare bloc de operație poartă un buton + Add, care creează o cerere preconfigurată pentru acea operație. Este calea cea mai scurtă atunci când un import a fost parțial sau când o operație tocmai a apărut în specificație.

Navigarea și căutarea

Un cuprins este ancorat în dreapta — secțiunile Overview, Operations, Models, Enums — pliabil și redimensionabil. Un clic pe un model derulează până la graf și centrează acolo nodul corespunzător.

Scurtătură	Efect
Ctrl+F / Cmd+F	Deschide căutarea în documentație
F3 / Enter	Potrivirea următoare
Shift+F3 / Shift+Enter	Potrivirea precedentă
Esc	Închide căutarea

Un contor indică poziția în rezultate.

Actualizarea documentației

O specificație evoluează. Restorm știe să aducă sursa și să aplice delta — documentație și cereri — fără să vă suprascrie munca.

Numai pentru importurile prin URL

Re-sincronizarea este disponibilă numai dacă folderul a fost importat de la un URL. Un import dintr-un fișier sau prin lipire nu înregistrează o sursă, iar butonul de actualizare nu apare: subfila de întâmpinare afișează atunci „Acest folder nu a fost creat dintr-o sursă importabilă.”

Acest URL nu poate fi modificat ulterior din interfață. Pentru a schimba sursa, refaceți un import.

Unde se află butonul

Două căi, echivalente:

1. subfila de întâmpinare a folderului de variabile, secțiunea Actualizări ale specificației — ea afișează URL-ul, Ultimul import și Ultima verificare și poartă butonul Actualizează;
2. clic dreapta pe folder în arborele lateral → Actualizează.

Nu există verificare automată

Restorm nu vă supraveghează specificațiile în fundal și nu vă va anunța că este disponibilă o versiune nouă. Verificarea este întotdeauna declanșată de dumneavoastră.

Ce se întâmplă

1. O fereastră „Actualizarea specificației…” apare pe durata recuperării. {{Variabilele}} din URL și din antete sunt rezolvate, iar ruta de autentificare atașată este rulată în prealabil.
2. Restorm compară o amprentă a sursei recuperate cu cea înregistrată la ultimul import.
3. Nimic nu s-a schimbat → „Specificația API-ului este la zi.”, și gata.
4. S-a schimbat ceva (sau recuperarea a eșuat) → se deschide asistentul de re-sincronizare.

Asistentul

• URL-ul sursă este afișat numai pentru citire.
• O pastilă permite atașarea, modificarea sau detașarea unei rute de autentificare, iar un submeniu Custom headers permite adăugarea de antete fixe, rulate la fiecare actualizare.
• Două file de previzualizare:
  • Routes — arborele operațiilor găsite în noua versiune, cu filtru și selecție. Operațiile deja prezente în folderul dumneavoastră sunt blocate și mereu bifate; alegeți doar care dintre cele noi se adaugă;
  • Documentation — documentația noii versiuni, numai pentru citire, înainte de a confirma.
• Butonul de confirmare afișează numărul de operații noi selectate, de exemplu Apply update (3).

Note

Asistentul este afișat astăzi în engleză, oricare ar fi limba aplicației („Refresh from source”, „Apply update”, filele „Routes” și „Documentation”). Denumirile în engleză sunt deci reluate aici ca atare.

Ce se modifică și ce nu

Acesta este punctul important: specificația are autoritate asupra a ceea ce descrie, dumneavoastră aveți autoritate asupra restului.

Element	Comportament
Numele unei cereri	Niciodată modificat
Metoda și URL-ul	Niciodată modificate
Parametrii, antetele și parametrii de cale existenți	Păstrați ca atare — valoare, descriere, activare
Parametri adăugați de specificație	Adăugați, cu valoarea implicită din specificație sau goi
Parametri retrași din specificație	Păstrați pe cerere
Operație nouă	Adăugată în locul în care ar fi pus-o un import nou (inclusiv folderul de etichetă)
Operație marcată depreciată de specificație	Semnalată; apare estompată în arbore
Operație dispărută din specificație	Semnalată ca retrasă; apare tăiată în arbore, rămâne executabilă și nu este ștearsă niciodată
Documentația de API și enumerările	Înlocuite integral cu noua versiune — asta reîmprospătează fila Docs

Nimic nu este șters vreodată din arborele dumneavoastră: o operație care dispare din sursă este marcată, nu ștearsă.

Dacă sursa cere o autentificare

Un răspuns 401 sau 403 deschide asistentul cu mesajul de eroare afișat ca atare (de exemplu HTTP 401: Unauthorized). Atașați o rută de autentificare sau adăugați antete fixe, iar previzualizarea este relansată.

Formate re-sincronizabile

Douăsprezece formate dispun de re-sincronizare: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC și Smithy.

Pentru toate celelalte, un import nou creează un arbore nou. Lista completă se află în Actualizarea din sursă.