{"id":38022,"date":"2019-10-31T22:21:14","date_gmt":"2019-10-31T19:21:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/tak-vse-taki-raml-ili-oas-swagger\/"},"modified":"2019-10-31T22:21:14","modified_gmt":"2019-10-31T19:21:14","slug":"tak-vse-taki-raml-ili-oas-swagger","status":"publish","type":"post","link":"https:\/\/prohoster.info\/sq\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"Pra, RAML apo OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

N\u00eb nj\u00eb bot\u00eb dinamike mikros services, gjith\u00e7ka mund t\u00eb ndryshoj\u00eb - \u00e7do komponent mund t\u00eb riprogramohet n\u00eb nj\u00eb gjuh\u00eb tjet\u00ebr, duke p\u00ebrdorur frameworke dhe arkitektura t\u00eb ndryshme. Ajo q\u00eb duhet t\u00eb mbetet e pandryshuar jan\u00eb kontratat, n\u00eb m\u00ebnyr\u00eb q\u00eb t\u00eb ket\u00eb nj\u00eb nd\u00ebrveprim t\u00eb vazhduesh\u00ebm me mikros services, pavar\u00ebsisht nga metamorfoza t\u00eb brendshme. Sot do t\u00eb flasim p\u00ebr problemin ton\u00eb t\u00eb zgjedhjes s\u00eb formatit t\u00eb p\u00ebrshkrimit t\u00eb kontratave dhe do t\u00eb ndajm\u00eb artefaktet e gjetura. <\/p>\n

\"Pra,
\n<\/a><\/noindex>
\nPostimi \u00ebsht\u00eb p\u00ebrgatitur nga Anna Melekova<\/a><\/noindex> dhe Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikroserviset.<\/b> Gjat\u00eb zhvillimit t\u00eb Acronis Cyber Cloud, kuptuam se nuk kishim ku t\u00eb iknim prej tyre. Dizajnimi i nj\u00eb mikros services nuk mund t\u00eb realizohet pa formalizimin e kontrat\u00ebs, e cila p\u00ebrfaq\u00ebson nd\u00ebrfaqen e mikros services.<\/p>\n

Por kur n\u00eb produkt ka m\u00eb shum\u00eb se nj\u00eb komponent, dhe zhvillimi i kontrat\u00ebs b\u00ebhet nj\u00eb aktivitet i rregullt, fillon t\u00eb mendosh p\u00ebr optimizimin e procesit. B\u00ebn t\u00eb dukshme se nd\u00ebrfaqja (kontrata) dhe implementimi (mikros services) duhet t\u00eb p\u00ebrputhen, q\u00eb komponent\u00ebt e ndrysh\u00ebm duhet t\u00eb b\u00ebjn\u00eb t\u00eb nj\u00ebjtat gj\u00ebra nj\u00ebsoj, dhe se pa nj\u00eb pranimin qendror t\u00eb t\u00eb gjitha k\u00ebtyre vendimeve, \u00e7do ekip do t\u00eb ishte i detyruar t\u00eb humbte koh\u00eb p\u00ebrs\u00ebri dhe p\u00ebrs\u00ebri p\u00ebr t'i marr\u00eb ato. <\/p>\n

\"Pra,
\nSkema e mikroserviseve Amazon nga tweet-i<\/a><\/noindex> i Werner Vogels, CTO i Amazon<\/i>
\n\u00c7far\u00eb \u00ebsht\u00eb dilema? N\u00eb fakt, ka dy m\u00ebnyra p\u00ebr nd\u00ebrveprimin e mikroserviseve - HTTP Rest dhe gRPC nga Google. T\u00eb mos d\u00ebshirojm\u00eb t\u00eb p\u00ebrfshihemi n\u00eb stek teknologjish t\u00eb Google, ne zgjodh\u00ebm HTTP Rest. Annotationet e kontratave HTTP REST zakonisht p\u00ebrshkruhen n\u00eb nj\u00eb nga dy formate: RAML dhe OAS, i njohur m\u00eb par\u00eb si Swagger. Prandaj, \u00e7do ekip zhvilluesish p\u00ebrballet me nevoj\u00ebn p\u00ebr t\u00eb b\u00ebr\u00eb nj\u00eb zgjedhje midis nj\u00ebrit prej standardeve. Por, si\u00e7 u zbulua, t\u00eb b\u00ebsh k\u00ebt\u00eb zgjedhje mund t\u00eb jet\u00eb shum\u00eb e v\u00ebshtir\u00eb.<\/p>\n

Pse nevojiten annotationet?<\/h3>\n

\nNj\u00eb p\u00ebrmbledhje \u00ebsht\u00eb e nevojshme q\u00eb p\u00ebrdoruesi i jasht\u00ebm t\u00eb mund t\u00eb kuptoj\u00eb leht\u00ebsisht se \u00e7far\u00eb mund t\u00eb b\u00ebj\u00eb me sh\u00ebrbimin tuaj n\u00ebp\u00ebrmjet nd\u00ebrfaqes s\u00eb tij HTTP. K\u00ebshtu q\u00eb, n\u00eb nj\u00eb nivel bazik, p\u00ebrmbledhja duhet t\u00eb p\u00ebrmbaj\u00eb t\u00eb pakt\u00ebn nj\u00eb list\u00eb t\u00eb burimeve t\u00eb disponueshme, metodave t\u00eb tyre HTTP, trupit t\u00eb k\u00ebrkesave, njohjen e parametrave, specifikimin e titujve t\u00eb nevojsh\u00ebm dhe t\u00eb mb\u00ebshtetur, si dhe kodeve t\u00eb kthimit dhe formateve t\u00eb p\u00ebrgjigjeve. Nj\u00eb element jasht\u00ebzakonisht t\u00eb r\u00ebnd\u00ebsish\u00ebm t\u00eb p\u00ebrmbledhjes s\u00eb kontrat\u00ebs \u00ebsht\u00eb dhe p\u00ebrshkrimi i tyre me fjal\u00eb (\u201c\u00e7far\u00eb do t\u00eb ndodh\u00eb n\u00ebse shtohet ky parametrat e k\u00ebrkes\u00ebs?\u201d, \u201cn\u00eb cilin rast do t\u00eb kthehet kodi 400?\u201d)<\/p>\n

Megjithat\u00eb, kur flitet p\u00ebr zhvillimin e nj\u00eb numri t\u00eb madh mikrosherbimesh, d\u00ebshira \u00ebsht\u00eb t\u00eb nxirret dobi shtes\u00eb nga p\u00ebrmbledhjet e shkruara. P\u00ebr shembull, mbi baz\u00ebn e RAML\/SWAGGER mund t\u00eb gjenerohet kod klienti dhe serveri n\u00eb nj\u00eb num\u00ebr t\u00eb madh gjuh\u00ebsh programimi. Po ashtu, mund t\u00eb p\u00ebrfitohet automatikisht dokumentacioni p\u00ebr mikrosherbimin dhe ta ngarkoni at\u00eb n\u00eb portalin tuaj p\u00ebr zhvilluesit :).<\/p>\n

\"Pra,
\nShembulli i p\u00ebrshkrimit t\u00eb strukturuar t\u00eb kontrat\u00ebs<\/i><\/p>\n

Praktika e testimit t\u00eb mikrosherbimeve mbi baz\u00ebn e p\u00ebrshkrimeve t\u00eb kontratave \u00ebsht\u00eb m\u00eb e rrall\u00eb. N\u00ebse keni shkruar si p\u00ebrmbledhjen ashtu edhe komponentin, mund t\u00eb krijoni nj\u00eb test automatik q\u00eb kontrollon funksionimin e sh\u00ebrbimit me lloje t\u00eb ndryshme t\u00eb t\u00eb dh\u00ebnave n\u00eb hyrje. A kthen sh\u00ebrbimi nj\u00eb kod p\u00ebrgjigjeje q\u00eb nuk \u00ebsht\u00eb p\u00ebrshkruar n\u00eb p\u00ebrmbledhje? A do t\u00eb jet\u00eb n\u00eb gjendje t\u00eb p\u00ebrpunoj\u00eb t\u00eb dh\u00ebna t\u00eb gabuara?<\/p>\n

P\u00ebr m\u00eb tep\u00ebr, nj\u00eb zbatim cil\u00ebsor jo vet\u00ebm i kontratave t\u00eb vetme, por gjithashtu i mjeteve p\u00ebr vizualizimin e p\u00ebrmbledhjeve aktualizon pun\u00ebn me mikrosherbimin. K\u00ebshtu q\u00eb n\u00ebse arkitekti e ka p\u00ebrshkruar mir\u00eb kontrat\u00ebn, n\u00eb baz\u00eb t\u00eb saj dizajner\u00ebt dhe zhvilluesit do ta integrojn\u00eb sh\u00ebrbimin n\u00eb produkte t\u00eb tjera pa shpenzuar koh\u00eb shtes\u00eb.<\/p>\n

P\u00ebr t\u00eb punuar me mjete shtes\u00eb, si RAML ashtu edhe OAS kan\u00eb mund\u00ebsin\u00eb e shtimit t\u00eb metadatatve, q\u00eb nuk jan\u00eb parashikuar nga standardi (p\u00ebr shembull, k\u00ebshtu b\u00ebhet n\u00eb OAS<\/a><\/noindex>).<\/p>\n

N\u00eb p\u00ebrgjith\u00ebsi, fusha p\u00ebr krijimtari n\u00eb aplikimin e kontratave p\u00ebr mikrosherbime \u00ebsht\u00eb e madhe... t\u00eb pakt\u00ebn teoritikisht<\/p>\n

Krahasimi i jezit me ujku<\/h3>\n

\nAktualisht, drejtimi kryesor i zhvillimit n\u00eb Acronis \u00ebsht\u00eb zhvillimi i Acronis Cyber Platform. Acronis Cyber Platform \u00ebsht\u00eb pik\u00ebt e reja t\u00eb integrimit t\u00eb sh\u00ebrbimeve t\u00eb jashtme me Acronis Cyber Cloud dhe pjes\u00ebn agjente. Edhe pse API-t\u00eb tona t\u00eb brendshme, t\u00eb p\u00ebrshkruara n\u00eb RAML, na k\u00ebnaqin, nevoja p\u00ebr publikimin e API-ve e ngre p\u00ebrs\u00ebri pyetjen: cili standard i anotimeve \u00ebsht\u00eb m\u00eb i mir\u00eb p\u00ebr pun\u00ebn ton\u00eb?<\/p>\n

Fillimisht dukej se kishte dy zgjidhje \u2014 ato jan\u00eb zhvillimet m\u00eb t\u00eb zakonshme RAML dhe Swagger (ose OAS). Por n\u00eb fakt u tregua se alternativat jan\u00eb t\u00eb pakt\u00ebn 3 ose m\u00eb shum\u00eb.<\/p>\n

Nga nj\u00ebra an\u00eb, ka RAML \u2013 nj\u00eb gjuh\u00eb e fuqishme dhe efektive. Ajo realizon mir\u00eb hierarkin\u00eb dhe trash\u00ebgimin\u00eb, k\u00ebshtu q\u00eb ky format \u00ebsht\u00eb m\u00eb i p\u00ebrshtatsh\u00ebm p\u00ebr kompanit\u00eb e m\u00ebdha q\u00eb kan\u00eb nevoj\u00eb p\u00ebr shum\u00eb p\u00ebrshkrime \u2014 pra, jo vet\u00ebm nj\u00eb produkt, por shum\u00eb mikro sh\u00ebrbime q\u00eb kan\u00eb pjes\u00eb t\u00eb p\u00ebrbashk\u00ebta t\u00eb kontratave \u2014 skemat e autentifikimit, t\u00eb nj\u00ebjtat tipe t\u00eb dh\u00ebnash, trupat e gabimeve.<\/p>\n

Por zhvilluesi i RAML, kompania Mulesoft, u bashkua me konsorciumin Open API, i cili merret me zhvillimin Swagger<\/a><\/noindex>. Prandaj RAML e ndali zhvillimin e tij. T\u00eb imagjinoni formatin e ngjarjes, imagjinoni q\u00eb mbajt\u00ebsit e komponenteve kryesore t\u00eb Linux shkuan t\u00eb punojn\u00eb n\u00eb Microsoft. Nj\u00eb situat\u00eb e till\u00eb krijon premisat p\u00ebr t\u00eb p\u00ebrdorur Swagger, i cili zhvillohet dinamike dhe n\u00eb versionin e tij t\u00eb tret\u00eb \u2014 praktikisht arrin RAML n\u00eb fleksibilitet dhe funksionalitet.<\/p>\n

N\u00ebse nuk do t\u00eb ishte nj\u00eb por...<\/h3>\n

\nSi\u00e7 doli, shum\u00eb prej mjeteve open-source nuk jan\u00eb p\u00ebrdit\u00ebsuar n\u00eb versionin OAS 3.0. P\u00ebr mikro sh\u00ebrbimet n\u00eb Go, m\u00eb kritikja do t\u00eb ishte mungesa e adaptimit t\u00eb go-swagger<\/a><\/noindex> p\u00ebr versionin e rinovuar t\u00eb standardit. Megjithat\u00eb, ndryshimi mes Swagger 2 dhe Swagger 3 \u00ebsht\u00eb i madh.<\/a><\/noindex>P\u00ebr shembull, n\u00eb versionin e tret\u00eb, zhvilluesit:<\/p>\n