Přístup k dokumentaci importovaného API a její aktualizace

Když importujete specifikaci, Restorm nevytváří jen požadavky: uchovává také dokumentaci API — popisy, modely, bezpečnostní schémata, příklady, výčtové typy — a připojuje ji ke složce proměnných vytvořené importem.

Přístup k dokumentaci

Karta Dokumentace složky proměnných

To je hlavní zobrazení. Otevřete složku proměnných vzniklou importem: v jejím řádku podkaret je karta Dokumentace, hned vedle karet Prostředí, Custom variables a Poznámky.

Karta se zobrazí jen tehdy, když složka pochází z importu — složka proměnných, kterou jste vytvořili ručně, žádnou dokumentaci k zobrazení nemá.

Další cesty k dokumentaci

Odkud	Co získáte
Karta Dokumentace na požadavku	Dokumentaci jediné této operace — bez obsahu a bez bloku obecných informací. Zobrazí se jen tehdy, když je operace nalezena ve specifikaci
Karta Dokumentace na jednoduché složce	Dokumentaci omezenou na operace, které tato složka obsahuje
Úvodní podkarta složky proměnných	Kartu Zobrazit dokumentaci — „Procházet dokumentaci API, modely a endpointy“
Úvodní obrazovka (karta API)	Rychlý odkaz Dokumentace
Vyhledávání v záhlaví okna	Náhled dokumentace při přejetí přes výsledek

Co zobrazení obsahuje

Odshora dolů:

• název API a jeho popis;
• blok informací: Version, Source format (s odkazem na zdrojovou URL), Server (schémata, hostitel, základní cesta), Contact, License, Terms of service, External docs;
• jednu sekci na štítek, s jeho popisem;
• jeden blok na operaci: metodu a URL, souhrn, odznak skupiny, případně odznak deprecated, sekci Security (typ schématu, toky OAuth 2, rozsahy) a rozbalitelný Example payload;
• tabulky Parameters a Responses (stavové kódy jsou barevně odlišené);
• Models — interaktivní graf schémat, po kterém lze navigovat a přibližovat jej;
• Polymorphism — kompozice oneOf / anyOf / allOf;
• Enums — výčtové typy, sloučené s těmi ze složky.

Note

Názvy těchto sekcí (Models, Enums, Parameters, Responses, Security, Example payload) se ve všech jazycích aplikace zobrazují v angličtině. Zde jsou proto uvedeny tak, jak jsou, abyste je na obrazovce našli.

Vytvoření požadavku z dokumentace

Každý blok operace nese tlačítko + Add, které vytvoří požadavek předem nastavený pro tuto operaci. To je nejkratší cesta, když byl import jen částečný nebo když se ve specifikaci právě objevila nová operace.

Navigace a hledání

Vpravo je ukotvený obsah — sekce Overview, Operations, Models, Enums — sbalitelný a s nastavitelnou šířkou. Kliknutí na model odroluje ke grafu a vycentruje v něm odpovídající uzel.

Zkratka	Účinek
Ctrl+F / Cmd+F	Otevře hledání v dokumentaci
F3 / Enter	Následující výskyt
Shift+F3 / Shift+Enter	Předchozí výskyt
Esc	Zavře hledání

Počítadlo ukazuje pozici mezi výsledky.

Aktualizace dokumentace

Specifikace se vyvíjí. Restorm umí zdroj znovu načíst a použít rozdíl — dokumentaci i požadavky — aniž by přepsal vaši práci.

Pouze pro importy z URL

Opětovná synchronizace je dostupná jen tehdy, když byla složka naimportována z URL. Import ze souboru nebo vložením obsahu žádný zdroj neukládá a tlačítko pro aktualizaci se nezobrazí: úvodní podkarta pak hlásí „Tato složka nebyla vytvořena z importovatelného zdroje.“

Tuto URL nelze později v rozhraní změnit. Chcete-li vyměnit zdroj, proveďte import znovu.

Kde tlačítko najdete

Dvě rovnocenné cesty:

1. úvodní podkarta složky proměnných, sekce Aktualizace specifikace API — zobrazuje URL, Poslední import a Poslední kontrola a nese tlačítko Aktualizovat;
2. kliknutí pravým tlačítkem na složku ve stromu v postranním panelu → Aktualizovat.

Žádná automatická kontrola neexistuje

Restorm vaše specifikace na pozadí nesleduje a neupozorní vás, že je dostupná nová verze. Kontrolu spouštíte vždy vy.

Co se stane

1. Během načítání se objeví okno „Aktualizace specifikace API…“. Zápisy {{variables}} v URL a v hlavičkách se vyhodnotí a připojená ověřovací trasa se předem spustí.
2. Restorm porovná otisk načteného zdroje s otiskem uloženým při posledním importu.
3. Nic se nezměnilo → „Specifikace API je aktuální.“ a tím to končí.
4. Něco se změnilo (nebo se načtení nepovedlo) → otevře se průvodce opětovnou synchronizací.

Průvodce

• Zdrojová URL se zobrazuje jen pro čtení.
• Jeden odznak umožňuje připojit, změnit nebo odpojit ověřovací trasu a podnabídka Custom headers přidat fixní hlavičky posílané při každé aktualizaci.
• Dvě karty s náhledem:
  • Routes — strom operací nalezených v nové verzi, s filtrem a výběrem. Operace, které už ve vaší složce jsou, jsou uzamčené a vždy zaškrtnuté; vybíráte pouze to, které z nových přidat;
  • Documentation — dokumentace nové verze, jen pro čtení, ještě před potvrzením.
• Potvrzovací tlačítko zobrazuje počet vybraných nových operací, například Apply update (3).

Note

Průvodce je dnes zobrazen v angličtině bez ohledu na jazyk aplikace („Refresh from source“, „Apply update“, karty „Routes“ a „Documentation“). Anglické názvy jsou zde proto uvedeny tak, jak jsou.

Co se změní a co ne

Právě to je podstatné: specifikace má autoritu nad tím, co popisuje, vy máte autoritu nad ostatním.

Prvek	Chování
Název požadavku	Nikdy se nemění
Metoda a URL	Nikdy se nemění
Existující parametry, hlavičky a parametry cesty	Zůstávají tak, jak jsou — hodnota, popis, zapnutí
Parametry přidané specifikací	Přidají se, s výchozí hodnotou ze specifikace, nebo prázdné
Parametry odebrané ze specifikace	Na požadavku zůstávají
Nová operace	Přidá se tam, kam by ji umístil nový import (včetně složky štítku)
Operace označená specifikací jako zavržená	Je označena; ve stromu se zobrazuje zesvětlená
Operace, která ze specifikace zmizela	Je označena jako odebraná; ve stromu se zobrazuje přeškrtnutá, zůstává spustitelná a nikdy se nesmaže
Dokumentace API a výčtové typy	Nahrazují se celé novou verzí — právě to obnovuje kartu Dokumentace

Z vašeho stromu se nikdy nic nesmaže: operace, která ze zdroje zmizí, se označí, nikoli vymaže.

Pokud zdroj vyžaduje ověření

Odpověď 401 nebo 403 otevře průvodce s chybovou zprávou zobrazenou tak, jak je (například HTTP 401: Unauthorized). Připojte ověřovací trasu nebo přidejte fixní hlavičky a náhled se spustí znovu.

Formáty, které lze znovu synchronizovat

Opětovnou synchronizaci má dvanáct formátů: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC a Smithy.

U všech ostatních vytvoří nový import nový strom. Úplný seznam je na stránce Aktualizace ze zdroje.