Pristup dokumentaciji uvezenog API-ja i njezino ažuriranje

Kada uvezete specifikaciju, Restorm ne stvara samo zahtjeve: čuva dokumentaciju API-ja — opise, modele, sigurnosne sheme, primjere, enumeracije — i pridružuje je mapi okruženja stvorenoj uvozom.

Pristup dokumentaciji

Kartica Docs mape okruženja

To je glavni prikaz. Otvorite mapu okruženja proizašlu iz uvoza: njezina traka podkartica nosi karticu Docs, uz Okruženja, Prilagođene varijable i Bilješke.

Kartica se pojavljuje samo ako mapa potječe iz uvoza — mapa okruženja koju ste izradili ručno nema dokumentaciju za prikaz.

Ostali pristupi

Odakle	Što dobivate
Kartica Docs nekog zahtjeva	Dokumentacija samo te operacije — bez sadržaja i bloka općih informacija. Pojavljuje se samo ako je operacija pronađena u specifikaciji
Kartica Docs neke obične mape	Dokumentacija ograničena na operacije koje ta mapa sadrži
Početna podkartica mape okruženja	Kartica Pogledaj dokumentaciju — „Pregledajte dokumentaciju API-ja, modele i endpointe”
Početni zaslon (API kartica)	Brza poveznica Dokumentacija
Tražilica u naslovnoj traci	Pregled dokumentacije pri prelasku pokazivačem preko rezultata

Što prikaz sadrži

Odozgo prema dolje:

• naslov API-ja i njegov opis;
• blok informacija: Version, Source format (s poveznicom na izvorni URL), Server (sheme, domaćin, osnovna putanja), Contact, License, Terms of service, External docs;
• po jedan odjeljak za svaku etiketu, s njezinim opisom;
• po jedan blok za svaku operaciju: metoda i URL, sažetak, pločica skupine, značka deprecated ako je potrebno, odjeljak Security (vrsta sheme, OAuth 2 tijekovi, opsezi) i sklopiv Example payload;
• tablice Parameters i Responses (statusni su kodovi obojeni);
• Models — interaktivan graf shema, po kojem se može kretati i zumirati;
• Polymorphism — kompozicije oneOf / anyOf / allOf;
• Enums — enumeracije, spojene s onima iz mape.

Note

Naslovi tih odjeljaka (Models, Enums, Parameters, Responses, Security, Example payload) prikazuju se na engleskom u svim jezicima aplikacije. Ovdje su preuzeti takvi kakvi jesu kako biste ih prepoznali na zaslonu.

Stvaranje zahtjeva iz dokumentacije

Svaki blok operacije nosi gumb + Add koji stvara zahtjev unaprijed podešen za tu operaciju. To je najkraći put kada je uvoz bio djelomičan ili kada se operacija tek pojavila u specifikaciji.

Kretanje i pretraživanje

Sadržaj je usidren desno — odjeljci Overview, Operations, Models, Enums — sklopiv i promjenjive veličine. Klik na model pomiče prikaz do grafa i u njemu centrira odgovarajući čvor.

Prečac	Učinak
Ctrl+F / Cmd+F	Otvara pretraživanje u dokumentaciji
F3 / Enter	Sljedeće podudaranje
Shift+F3 / Shift+Enter	Prethodno podudaranje
Esc	Zatvara pretraživanje

Brojač prikazuje položaj među rezultatima.

Ažuriranje dokumentacije

Specifikacija se mijenja. Restorm zna dohvatiti izvor i primijeniti razliku — i dokumentaciju i zahtjeve — bez brisanja vašeg rada.

Samo za uvoze putem URL-a

Ponovna sinkronizacija dostupna je samo ako je mapa uvezena s URL-a. Uvoz iz datoteke ili lijepljenjem ne bilježi izvor i gumb za osvježavanje ne pojavljuje se: početna podkartica tada prikazuje „Ova mapa nije stvorena iz izvora koji se može uvesti.”

Taj se URL naknadno ne može mijenjati u sučelju. Za promjenu izvora ponovite uvoz.

Gdje se nalazi gumb

Dva ulaza, istovrijedna:

1. početna podkartica mape okruženja, odjeljak Ažuriranja specifikacije — prikazuje URL, Posljednji uvoz i Posljednja provjera, a nosi gumb Osvježi;
2. desni klik na mapu u bočnom stablu → Osvježi.

Nema automatske provjere

Restorm ne nadzire vaše specifikacije u pozadini i neće vas obavijestiti da je dostupna nova verzija. Provjeru uvijek pokrećete vi.

Što se događa

1. Tijekom dohvata pojavljuje se prozor „Osvježavanje specifikacije…”. {{Varijable}} iz URL-a i zaglavlja razrješavaju se, a pridružena se ruta autentifikacije prethodno odigra.
2. Restorm uspoređuje otisak dohvaćenog izvora s onim zabilježenim pri posljednjem uvozu.
3. Ništa se nije promijenilo → „Specifikacija API-ja je ažurna.” i time je gotovo.
4. Nešto se promijenilo (ili dohvat nije uspio) → otvara se čarobnjak za ponovnu sinkronizaciju.

Čarobnjak

• Izvorni URL prikazan je samo za čitanje.
• Pločica omogućuje pridruživanje, izmjenu ili odvajanje rute autentifikacije, a podizbornik Custom headers dodavanje fiksnih zaglavlja koja se ponavljaju pri svakom osvježavanju.
• Dvije kartice pretpregleda:
  • Routes — stablo operacija pronađenih u novoj verziji, s filtrom i odabirom. Operacije već prisutne u vašoj mapi zaključane su i uvijek označene; vi birate samo koje nove dodati;
  • Documentation — dokumentacija nove verzije, samo za čitanje, prije potvrde.
• Gumb za potvrdu prikazuje broj odabranih novih operacija, primjerice Apply update (3).

Note

Čarobnjak se danas prikazuje na engleskom bez obzira na jezik aplikacije („Refresh from source”, „Apply update”, kartice „Routes” i „Documentation”). Engleski su nazivi stoga ovdje preuzeti takvi kakvi jesu.

Što se mijenja, a što ne

To je važna točka: specifikacija je mjerodavna za ono što opisuje, vi ste mjerodavni za ostalo.

Element	Ponašanje
Naziv zahtjeva	Nikada se ne mijenja
Metoda i URL	Nikada se ne mijenjaju
Postojeći parametri, zaglavlja i parametri putanje	Čuvaju se takvi kakvi jesu — vrijednost, opis, aktivacija
Parametri koje specifikacija dodaje	Dodaju se, sa zadanom vrijednošću iz specifikacije ili prazni
Parametri uklonjeni iz specifikacije	Ostaju na zahtjevu
Nova operacija	Dodaje se na mjesto na koje bi je smjestio svježi uvoz (uključujući mapu etikete)
Operacija koju specifikacija označi zastarjelom	Označava se; u stablu se pojavljuje izblijedjelo
Operacija nestala iz specifikacije	Označava se kao uklonjena; u stablu se pojavljuje precrtano, ostaje izvediva i nikada se ne briše
API dokumentacija i enumeracije	Potpuno se zamjenjuju novom verzijom — to je ono što osvježava karticu Docs

Iz vašeg se stabla nikada ništa ne briše: operacija koja nestane iz izvora označava se, ne uklanja.

Ako izvor traži autentifikaciju

Odgovor 401 ili 403 otvara čarobnjaka s prikazanom porukom pogreške takvom kakva jest (primjerice HTTP 401: Unauthorized). Pridružite rutu autentifikacije ili dodajte fiksna zaglavlja pa se pretpregled ponovno pokreće.

Formati koji se mogu ponovno sinkronizirati

Ponovnom sinkronizacijom raspolaže dvanaest formata: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC i Smithy.

Za sve ostale novi uvoz stvara novo stablo. Potpun je popis u članku Ažuriranje iz izvora.