Qasja dhe përditësimi i dokumentacionit të një API-je të importuar

Kur importoni një specifikim, Restorm nuk krijon vetëm kërkesa: ai ruan edhe dokumentacionin e API-së — përshkrime, modele, skema sigurie, shembuj, numërime — dhe ia bashkëngjit dosjes së variablave të krijuar nga importimi.

Qasja te dokumentacioni

Skeda Docs e dosjes së variablave

Kjo është pamja kryesore. Hapni dosjen e variablave që del nga importimi: shiriti i saj i nënskedave mban një skedë Docs, pranë Mjediset, Variablat e personalizuara dhe Shënimet.

Skeda shfaqet vetëm nëse dosja vjen nga një importim — një dosje variablash që e keni krijuar me dorë nuk ka dokumentacion për të shfaqur.

Qasjet e tjera

Nga	Çfarë merrni
Skeda Docs e një kërkese	Dokumentacioni i vetëm atij veprimi — pa përmbajtje dhe pa bllok informacionesh të përgjithshme. Ajo shfaqet vetëm nëse veprimi gjendet brenda specifikimit
Skeda Docs e një dosjeje të thjeshtë	Dokumentacioni i kufizuar te veprimet që përmban ajo dosje
Nënskeda e mirëseardhjes e dosjes së variablave	Karta Shiko dokumentacionin — «Shfletoni dokumentacionin e API-së, modelet dhe endpoint-et»
Ekrani i mirëseardhjes (karta API)	Lidhja e shpejtë Dokumentacioni
Motori i kërkimit i shiritit të titullit	Një parapamje e dokumentacionit kur kaloni kursorin mbi një rezultat

Çfarë përmban pamja

Nga lart poshtë:

• titulli i API-së dhe përshkrimi i saj;
• një bllok informacionesh: Version, Source format (me një lidhje drejt URL-së burimore), Server (skemat, hosti, shtegu bazë), Contact, License, Terms of service, External docs;
• një seksion për çdo etiketë, me përshkrimin e vet;
• një bllok për çdo veprim: metoda dhe URL-ja, përmbledhja, pastila e grupit, stema deprecated nëse është rasti, seksioni Security (tipi i skemës, flukset OAuth 2, shtrirjet) dhe një Example payload i palosshëm;
• tabelat Parameters dhe Responses (kodet e statusit janë me ngjyra);
• Models — një graf interaktiv i skemave, i lundrueshëm dhe i zmadhueshëm;
• Polymorphism — përbërjet oneOf / anyOf / allOf;
• Enums — numërimet, të bashkuara me ato të dosjes.

Note

Titujt e këtyre seksioneve (Models, Enums, Parameters, Responses, Security, Example payload) shfaqen në anglisht në të gjitha gjuhët e aplikacionit. Ata janë marrë ashtu siç janë edhe këtu që t’i gjeni njësoj në ekran.

Krijimi i një kërkese nga dokumentacioni

Çdo bllok veprimi mban një buton + Add që krijon një kërkesë të parakonfiguruar për atë veprim. Kjo është rruga më e shkurtër kur një importim ka qenë i pjesshëm, ose kur një veprim sapo është shfaqur në specifikim.

Lundrimi dhe kërkimi

Një përmbajtje është e ankoruar djathtas — seksionet Overview, Operations, Models, Enums — e palosshme dhe e ripërmasueshme. Klikimi mbi një model rrëshqet deri te grafi dhe e vendos në qendër nyjën përkatëse.

Shkurtorja	Efekti
Ctrl+F / Cmd+F	Hap kërkimin brenda dokumentacionit
F3 / Enter	Përputhja pasuese
Shift+F3 / Shift+Enter	Përputhja e mëparshme
Esc	Mbyll kërkimin

Një numërues tregon pozicionin brenda rezultateve.

Përditësimi i dokumentacionit

Një specifikim ndryshon. Restorm di ta kërkojë burimin dhe të zbatojë deltën — dokumentacionin dhe kërkesat — pa e shkatërruar punën tuaj.

Vetëm për importimet me URL

Risinkronizimi është i disponueshëm vetëm nëse dosja është importuar nga një URL. Një importim nga një skedar ose me ngjitje nuk regjistron ndonjë burim dhe butoni i përditësimit nuk shfaqet: nënskeda e mirëseardhjes shfaq atëherë «Kjo dosje nuk është krijuar nga një burim i importueshëm.»

Kjo URL nuk mund të ndryshohet më pas nga ndërfaqja. Për të ndërruar burimin, ribëni një importim.

Ku ndodhet butoni

Dy hyrje, të barasvlershme:

1. nënskeda e mirëseardhjes e dosjes së variablave, seksioni Përditësimet e specifikimit — ajo shfaq URL-në, Importimin e fundit dhe Kontrollin e fundit, dhe mban butonin Përditëso;
2. klik me të djathtën mbi dosjen në pemën anësore → Përditëso.

Nuk ka kontroll automatik

Restorm nuk i mbikëqyr specifikimet tuaja në sfond dhe nuk do t’ju paralajmërojë se ka dalë një version i ri. Kontrolli niset gjithmonë nga ju.

Çfarë ndodh

1. Një dritare «Përditësimi i specifikimit…» shfaqet gjatë marrjes. {{variables}} e URL-së dhe të kokave zgjidhen, ndërsa rruga e vërtetimit e bashkëngjitur luhet paraprakisht.
2. Restorm krahason një gjurmë të burimit të marrë me atë të regjistruar gjatë importimit të fundit.
3. Asgjë nuk ka ndryshuar → «Specifikimi i API-së është i përditësuar.», dhe kaq.
4. Diçka ka ndryshuar (ose marrja dështoi) → hapet asistenti i risinkronizimit.

Asistenti

• URL-ja burimore shfaqet vetëm për lexim.
• Një pastilë lejon bashkëngjitjen, modifikimin ose shkëputjen e një rruge vërtetimi, ndërsa një nënmenu Custom headers lejon shtimin e kokave fikse që luhen sërish në çdo përditësim.
• Dy skeda parapamjeje:
  • Routes — pema e veprimeve të gjetura në versionin e ri, me filtër dhe përzgjedhje. Veprimet tashmë të pranishme në dosjen tuaj janë të kyçura dhe gjithmonë të shënuara; ju zgjidhni vetëm cilat prej veprimeve të reja do të shtoni;
  • Documentation — dokumentacioni i versionit të ri, vetëm për lexim, përpara se të validoni.
• Butoni i validimit shfaq numrin e veprimeve të reja të zgjedhura, për shembull Apply update (3).

Note

Asistenti shfaqet sot në anglisht cilado qoftë gjuha e aplikacionit («Refresh from source», «Apply update», skedat «Routes» dhe «Documentation»). Titujt në anglisht janë marrë pra ashtu siç janë edhe këtu.

Çfarë ndryshohet dhe çfarë jo

Kjo është pika e rëndësishme: specifikimi ka autoritetin mbi atë që përshkruan, ju keni autoritetin mbi pjesën tjetër.

Elementi	Sjellja
Emri i një kërkese	Kurrë i ndryshuar
Metoda dhe URL-ja	Kurrë të ndryshuara
Parametrat, kokat dhe parametrat e shtegut ekzistuese	Ruhen ashtu siç janë — vlera, përshkrimi, aktivizimi
Parametrat e shtuar nga specifikimi	Shtohen, me vlerën e parazgjedhur të specifikimit ose bosh
Parametrat e hequr nga specifikimi	Ruhen mbi kërkesën
Veprim i ri	Shtohet aty ku do ta kishte vendosur një importim i ri (përfshirë dosjen e etiketës)
Veprim i shënuar i vjetruar nga specifikimi	Sinjalizohet; ai shfaqet i zbehtë në pemë
Veprim i zhdukur nga specifikimi	Sinjalizohet si i hequr; ai shfaqet i vijëzuar në pemë, mbetet i ekzekutueshëm dhe nuk fshihet kurrë
Dokumentacioni i API-së dhe numërimet	Zëvendësohen tërësisht me versionin e ri — kjo është ajo që rifreskon skedën Docs

Asgjë nuk fshihet kurrë nga pema juaj: një veprim që zhduket nga burimi shënohet, nuk shlyhet.

Nëse burimi kërkon vërtetim

Një përgjigje 401 ose 403 e hap asistentin me mesazhin e gabimit të shfaqur ashtu siç është (për shembull HTTP 401: Unauthorized). Bashkëngjitni një rrugë vërtetimi ose shtoni koka fikse dhe parapamja rinisë.

Formatet e risinkronizueshme

Dymbëdhjetë formate e kanë risinkronizimin: Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC dhe Smithy.

Për të gjitha të tjerat, një importim i ri krijon një pemë të re. Lista e plotë gjendet te Përditësimi nga burimi.