Pristup dokumentaciji uvezenog API-ja i njeno ažuriranje

Kada uvezete specifikaciju, Restorm ne pravi samo zahteve: on čuva dokumentaciju API-ja — opise, modele, bezbednosne šeme, primere, enumeracije — i prilaže je uz fasciklu promenljivih napravljenu uvozom.

Pristup dokumentaciji

Kartica Docs fascikle promenljivih

To je glavni prikaz. Otvorite fasciklu promenljivih proisteklu iz uvoza: njena traka podkartica nosi karticu Docs, pored Okruženja, Prilagođene promenljive i Beleške.

Kartica se pojavljuje samo ako fascikla potiče iz uvoza — fascikla promenljivih koju ste sami napravili nema dokumentaciju za prikaz.

Ostali pristupi

Odakle	Šta dobijate
Kartica Docs nekog zahteva	Dokumentacija samo te operacije — bez sadržaja i bez bloka sa opštim informacijama. Pojavljuje se samo ako je operacija pronađena u specifikaciji
Kartica Docs neke obične fascikle	Dokumentacija ograničena na operacije koje ta fascikla sadrži
Početna podkartica fascikle promenljivih	Kartica Vidi dokumentaciju — „Pregledajte dokumentaciju API-ja, modele i krajnje tačke”
Ekran dobrodošlice (API kartica)	Brza veza Dokumentacija
Pretraživač iz naslovne trake	Pregled dokumentacije pri prelasku mišem preko rezultata

Šta prikaz sadrži

Odozgo nadole:

• naslov API-ja i njegov opis;
• blok informacija: Version, Source format (sa vezom ka izvornom URL-u), Server (šeme, host, osnovna putanja), Contact, License, Terms of service, External docs;
• po jedan odeljak za svaku etiketu, sa njenim opisom;
• po jedan blok za svaku operaciju: metoda i URL, sažetak, pastila grupe, značka deprecated po potrebi, odeljak Security (tip šeme, OAuth 2 tokovi, opsezi) i sklopivi Example payload;
• tabele Parameters i Responses (statusni kodovi su obojeni);
• Models — interaktivan graf šema, po kome se može kretati i zumirati;
• Polymorphism — kompozicije oneOf / anyOf / allOf;
• Enums — enumeracije, spojene sa onima iz fascikle.

Note

Nazivi ovih odeljaka (Models, Enums, Parameters, Responses, Security, Example payload) prikazuju se na engleskom na svim jezicima aplikacije. Ovde su preuzeti takvi kakvi jesu, da biste ih prepoznali na ekranu.

Pravljenje zahteva iz dokumentacije

Svaki blok operacije nosi dugme + Add koje pravi zahtev unapred podešen za tu operaciju. To je najkraći put kada je uvoz bio delimičan ili kada se operacija tek pojavila u specifikaciji.

Kretanje i pretraga

Sadržaj je usidren desno — odeljci Overview, Operations, Models, Enums — sklopiv i sa promenljivom veličinom. Klik na model skroluje do grafa i centrira odgovarajući čvor u njemu.

Prečica	Efekat
Ctrl+F / Cmd+F	Otvara pretragu u dokumentaciji
F3 / Enter	Sledeće podudaranje
Shift+F3 / Shift+Enter	Prethodno podudaranje
Esc	Zatvara pretragu

Brojač pokazuje poziciju u rezultatima.

Ažuriranje dokumentacije

Specifikacija se menja. Restorm ume da preuzme izvor i primeni deltu — dokumentaciju i zahteve — bez prebrisavanja vašeg rada.

Samo za uvoze sa URL-a

Ponovna sinhronizacija dostupna je samo ako je fascikla uvezena sa URL-a. Uvoz iz datoteke ili lepljenjem ne beleži izvor i dugme za osvežavanje se ne pojavljuje: početna podkartica tada prikazuje „Ova fascikla nije napravljena iz izvora koji se može uvoziti.”

Taj URL se ne može naknadno menjati u interfejsu. Da biste promenili izvor, napravite nov uvoz.

Gde se nalazi dugme

Dva ulaza, ekvivalentna:

1. početna podkartica fascikle promenljivih, odeljak Ažuriranja specifikacije — prikazuje URL, Poslednji uvoz i Poslednja provera, i nosi dugme Osveži;
2. desni klik na fasciklu u bočnom stablu → Osveži.

Nema automatske provere

Restorm ne nadzire vaše specifikacije u pozadini i neće vas obavestiti da je dostupna nova verzija. Proveru uvek pokrećete vi.

Šta se dešava

1. Tokom preuzimanja pojavljuje se prozor „Osvežavanje specifikacije…”. {{variables}} iz URL-a i zaglavlja se razrešavaju, a prikačena ruta autentifikacije se prethodno odigrava.
2. Restorm poredi otisak preuzetog izvora sa onim zabeleženim pri poslednjem uvozu.
3. Ništa se nije promenilo → „Specifikacija API-ja je ažurna.”, i to je kraj.
4. Nešto se promenilo (ili preuzimanje nije uspelo) → otvara se čarobnjak za ponovnu sinhronizaciju.

Čarobnjak

• Izvorni URL prikazuje se samo za čitanje.
• Pastila omogućava da prikačite, izmenite ili odvojite rutu autentifikacije, a podmeni Custom headers da dodate fiksna zaglavlja koja se ponovo šalju pri svakom osvežavanju.
• Dve kartice pregleda:
  • Routes — stablo operacija pronađenih u novoj verziji, sa filterom i izborom. Operacije koje već postoje u vašoj fascikli zaključane su i uvek označene; vi birate samo koje od novih dodati;
  • Documentation — dokumentacija nove verzije, samo za čitanje, pre potvrđivanja.
• Dugme za potvrdu prikazuje broj izabranih novih operacija, na primer 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 nazivi ovde su stoga preuzeti takvi kakvi jesu.

Šta se menja, a šta ne

To je važna stvar: specifikacija ima vlast nad onim što opisuje, a vi imate vlast nad ostatkom.

Element	Ponašanje
Naziv zahteva	Nikada se ne menja
Metoda i URL	Nikada se ne menjaju
Postojeći parametri, zaglavlja i parametri putanje	Čuvaju se takvi kakvi jesu — vrednost, opis, uključenost
Parametri dodati specifikacijom	Dodaju se, sa podrazumevanom vrednošću iz specifikacije ili prazni
Parametri uklonjeni iz specifikacije	Čuvaju se na zahtevu
Nova operacija	Dodaje se na mesto na koje bi je smestio svež uvoz (uključujući i fasciklu etikete)
Operacija koju specifikacija označi kao zastarelu	Signalizira se; u stablu se prikazuje izbledela
Operacija nestala iz specifikacije	Signalizira se kao uklonjena; u stablu se prikazuje precrtana, ostaje izvršna i nikada se ne briše
API dokumentacija i enumeracije	U celini se zamenjuju novom verzijom — to je ono što osvežava karticu Docs

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

Ako izvor traži autentifikaciju

Odgovor 401 ili 403 otvara čarobnjak sa porukom o grešci prikazanom takvom kakva jeste (na primer HTTP 401: Unauthorized). Prikačite rutu autentifikacije ili dodajte fiksna zaglavlja, i pregled se ponovo pokreće.

Formati pogodni za ponovnu sinhronizaciju

Ponovnu sinhronizaciju ima 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 pravi novo stablo. Kompletna lista je u Ažuriranje iz izvora.