Importált API dokumentációjának elérése és frissítése

Egy specifikáció importálásakor a Restorm nem csak kéréseket hoz létre: megőrzi az API dokumentációját is — leírásokat, modelleket, biztonsági sémákat, példákat, felsorolásokat —, és az importálás által létrehozott környezeti mappához csatolja.

A dokumentáció elérése

A környezeti mappa Dokumentáció lapja

Ez a fő nézet. Az importálásból származó környezeti mappát megnyitva az allapok sávján a Környezetek, az Egyéni változók és a Jegyzetek mellett egy Dokumentáció lap is szerepel.

A lap csak akkor jelenik meg, ha a mappa importálásból származik — egy kézzel létrehozott környezeti mappának nincs megjelenítendő dokumentációja.

A többi elérési út

Honnan	Mit ad
Egy kérés Dokumentáció lapja	Csak annak az egy műveletnek a dokumentációja — tartalomjegyzék és általános információs blokk nélkül. Csak akkor jelenik meg, ha a művelet megtalálható a specifikációban
Egy egyszerű mappa Dokumentáció lapja	Az adott mappában található műveletekre szűkített dokumentáció
A környezeti mappa kezdőlap allapja	A Dokumentáció megtekintése kártya — „Böngéssze az API dokumentációját, modelljeit és végpontjait”
A kezdőképernyő (API-kártya)	A Dokumentáció gyors hivatkozás
A címsor keresőmotorja	A dokumentáció előnézete, ha az egérrel egy találat fölé állunk

A nézet tartalma

Felülről lefelé:

• az API címe és leírása;
• egy információs blokk: Version, Source format (a forrás URL-jére mutató hivatkozással), Server (sémák, gazdagép, alapútvonal), Contact, License, Terms of service, External docs;
• címkénként egy szakasz, a saját leírásával;
• műveletenként egy blokk: metódus és URL, összefoglaló, csoportjelvény, szükség esetén deprecated jelvény, Security szakasz (a séma típusa, OAuth 2 folyamok, jogosultsági körök), valamint egy összecsukható Example payload;
• a Parameters és a Responses táblázat (az állapotkódok színezve);
• Models — a sémák interaktív gráfja, amelyben lehet navigálni és nagyítani;
• Polymorphism — az oneOf / anyOf / allOf összetételek;
• Enums — a felsorolások, a mappáéival egyesítve.

Note

Ezek a szakaszcímek (Models, Enums, Parameters, Responses, Security, Example payload) az alkalmazás minden nyelvén angolul jelennek meg. Itt ezért változtatás nélkül szerepelnek, hogy a képernyőn is felismerhetők legyenek.

Kérés létrehozása a dokumentációból

Minden műveleti blokkon van egy + Add gomb, amely az adott művelethez előre beállított kérést hoz létre. Ez a legrövidebb út, ha egy importálás részleges maradt, vagy ha egy művelet éppen most jelent meg a specifikációban.

Navigálás és keresés

A jobb oldalon tartalomjegyzék van kihorgonyozva — Overview, Operations, Models, Enums szakaszokkal —, amely összecsukható és átméretezhető. Egy modellre kattintva a nézet a gráfhoz görget, és rá is középre állítja a megfelelő csomópontot.

Billentyűparancs	Hatás
Ctrl+F / Cmd+F	Megnyitja a keresést a dokumentációban
F3 / Enter	Következő találat
Shift+F3 / Shift+Enter	Előző találat
Esc	Bezárja a keresést

Egy számláló jelzi a találatok közötti helyzetet.

A dokumentáció frissítése

Egy specifikáció változik. A Restorm képes újra letölteni a forrást, és a különbséget — a dokumentációra és a kérésekre egyaránt — anélkül alkalmazni, hogy a már elvégzett munka elveszne.

Csak az URL-ről történt importálásokra

Az újraszinkronizálás csak akkor érhető el, ha a mappa URL-ről lett importálva. A fájlból vagy beillesztésből származó importálás nem ment forrást, és a frissítés gombja sem jelenik meg: a kezdőlap allapja ilyenkor a „Ez a mappa nem importálható forrásból jött létre.” üzenetet mutatja.

Ez az URL utólag nem módosítható a felületen. Forrásváltáshoz újra kell importálni.

Hol található a gomb

Két egyenértékű belépési pont van:

1. a környezeti mappa kezdőlap allapja, az API-specifikáció frissítései szakasz — ez megjeleníti az URL-t, az Utolsó importálás és az Utolsó ellenőrzés értékét, és rajta van a Frissítés gomb;
2. jobb gombos kattintás a mappára az oldalsáv fájában → Frissítés.

Automatikus ellenőrzés nincs

A Restorm nem figyeli a specifikációkat a háttérben, és nem jelzi, ha új változat érhető el. Az ellenőrzést mindig a felhasználó indítja.

Mi történik

1. A letöltés közben megjelenik egy „API-specifikáció frissítése…” ablak. Az URL és a fejlécek {{variables}} hivatkozásai feloldódnak, a csatolt hitelesítési útvonal pedig előzetesen lefut.
2. A Restorm összehasonlítja a letöltött forrás ujjlenyomatát azzal, amelyet az utolsó importáláskor mentett.
3. Semmi nem változott → „Az API-specifikáció naprakész.”, és ezzel kész.
4. Valami megváltozott (vagy a letöltés meghiúsult) → megnyílik az újraszinkronizálási varázsló.

A varázsló

• A forrás URL-je csak olvasható módon látszik.
• Egy jelvényen keresztül lehet hitelesítési útvonalat csatolni, módosítani vagy leválasztani, a Custom headers almenüvel pedig minden frissítéskor újrajátszott fix fejléceket hozzáadni.
• Két előnézeti lap:
  • Routes — az új változatban talált műveletek fája, szűrővel és kijelöléssel. A mappában már meglévő műveletek zárolva vannak és mindig be vannak jelölve; csak az újak közül kell választani, melyek kerüljenek be;
  • Documentation — az új változat dokumentációja, csak olvasható módon, a jóváhagyás előtt.
• A jóváhagyó gomb a kijelölt új műveletek számát jelzi, például Apply update (3).

Note

A varázsló ma az alkalmazás nyelvétől függetlenül angolul jelenik meg („Refresh from source”, „Apply update”, „Routes” és „Documentation” lapok). Az angol feliratok ezért itt is változtatás nélkül szerepelnek.

Mi módosul, és mi nem

Ez a lényeg: a specifikáció mérvadó abban, amit leír, minden másban a felhasználó a mérvadó.

Elem	Viselkedés
Egy kérés neve	Soha nem módosul
Metódus és URL	Soha nem módosul
A meglévő paraméterek, fejlécek és útvonalparaméterek	Változatlanul megmaradnak — érték, leírás, engedélyezés
A specifikáció által hozzáadott paraméterek	Bekerülnek, a specifikáció alapértelmezett értékével vagy üresen
A specifikációból kivett paraméterek	Megmaradnak a kérésen
Új művelet	Bekerül arra a helyre, ahová egy új importálás is helyezte volna (a címkemappát is beleértve)
A specifikáció által elavultnak jelölt művelet	Megjelölve; elhalványítva jelenik meg a fában
A specifikációból eltűnt művelet	Visszavontként megjelölve; áthúzva jelenik meg a fában, futtatható marad, és soha nem törlődik
API-dokumentáció és felsorolások	Teljes egészében kicserélve az új változatra — ez frissíti a Dokumentáció lapot

A fából soha nem törlődik semmi: a forrásból eltűnő művelet megjelölést kap, nem törlést.

Ha a forrás hitelesítést kér

A 401 vagy 403 válasz megnyitja a varázslót, és változtatás nélkül megjeleníti a hibaüzenetet (például HTTP 401: Unauthorized). Ilyenkor egy hitelesítési útvonalat kell csatolni vagy fix fejléceket hozzáadni, és az előnézet újraindul.

Újraszinkronizálható formátumok

Tizenkét formátum támogatja az újraszinkronizálást: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC és Smithy.

Az összes többinél egy újabb importálás új fát hoz létre. A teljes lista itt található: Frissítés a forrásból.