{"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 bot\u00ebn dinamike t\u00eb mikroservic\u00ebve, gjith\u00e7ka mund t\u00eb ndryshoj\u00eb \u2014 \u00e7do komponent mund t\u00eb rikadohet n\u00eb nj\u00eb gjuh\u00eb tjet\u00ebr, duke p\u00ebrdorur framework-e dhe arkitektur\u00eb t\u00eb tjera. Ajo q\u00eb duhet t\u00eb mbetet e pandryshueshme jan\u00eb kontratat, p\u00ebr t'u mund\u00ebsuar bashk\u00ebveprimin me mikroservicin nga jasht\u00eb n\u00eb nj\u00eb baz\u00eb t\u00eb q\u00ebndrueshme, pavar\u00ebsisht metamorfosave 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 Melekhova<\/a><\/noindex> dhe Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikroservic\u00ebt.<\/b> Gjat\u00eb zhvillimit t\u00eb Acronis Cyber Cloud, kuptuam se nuk mund t\u00eb shmangnim mikroservic\u00ebt. Projektimi i nj\u00eb mikroservici \u00ebsht\u00eb i pamundur pa formalisht kontrat\u00ebn, e cila p\u00ebrb\u00ebn nd\u00ebrfaqen e mikroservicit.<\/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 shfaqet nevoja p\u00ebr optimizimin e procesit. Duksh\u00ebm \u00ebsht\u00eb evidente se nd\u00ebrfaqja (kontrata) dhe implementimi (mikroservici) duhet t\u00eb harmonizohen, q\u00eb komponent\u00ebt e ndrysh\u00ebm duhet t\u00eb kryejn\u00eb t\u00eb nj\u00ebjtat funksione n\u00eb m\u00ebnyr\u00eb t\u00eb nj\u00ebjt\u00eb, dhe se pa nj\u00eb vendim t\u00eb centralizuar p\u00ebr t\u00eb gjith\u00eb k\u00ebto, \u00e7do ekip do t\u00eb detyrohet t\u00eb harxhoj\u00eb koh\u00eb p\u00ebrs\u00ebri dhe p\u00ebrs\u00ebri p\u00ebr t'i marr\u00eb ato. <\/p>\n

\"Pra,
\nSkema e mikroservic\u00ebve t\u00eb Amazon nga tweeti<\/a><\/noindex> i Werner Vogels, CTO i Amazon<\/i>
\nCila \u00ebsht\u00eb dilema? N\u00eb fakt, ka dy m\u00ebnyra interaktoni me mikroservic\u00ebt \u2013 HTTP Rest dhe gRPC nga Google. Duke mos d\u00ebshiruar t\u00eb p\u00ebrfshihesh n\u00eb stack-un e teknologjive t\u00eb Google, ne zgjodh\u00ebm HTTP Rest. Annotimet e kontratave HTTP REST shpesh p\u00ebrshkruhen n\u00eb nj\u00eb nga dy formate: RAML dhe OAS, t\u00eb njohura m\u00eb par\u00eb si Swagger. Prandaj, \u00e7do ekip zhvillues has nevoj\u00ebn p\u00ebr t\u00eb zgjedhur nj\u00eb nga standardet. Por, si\u00e7 doli, t\u00eb b\u00ebsh k\u00ebt\u00eb zgjedhje mund t\u00eb jet\u00eb shum\u00eb e v\u00ebshtir\u00eb.<\/p>\n

Pse nevojiten annotimet?<\/h3>\n

\nAnnotimi \u00ebsht\u00eb i nevojsh\u00ebm 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 p\u00ebrmes nd\u00ebrfaqes s\u00eb tij HTTP. K\u00ebshtu, n\u00eb nivelin bazik, annotimi duhet t\u00eb p\u00ebrmbaj\u00eb t\u00eb pakt\u00ebn nj\u00eb list\u00eb t\u00eb burimeve t\u00eb disponueshme, metodat e tyre HTTP, trupat e k\u00ebrkesave, renditjen e parametrave, p\u00ebrcaktimin e headereve t\u00eb nevojshme dhe t\u00eb mb\u00ebshtetur, si dhe kodet e kthimit dhe formatet e p\u00ebrgjigjeve. Nj\u00eb element shum\u00eb i r\u00ebnd\u00ebsish\u00ebm i annotimit t\u00eb kontrat\u00ebs \u00ebsht\u00eb edhe p\u00ebrshkrimi i tyre verbal (\u201c\u00e7far\u00eb do t\u00eb ndodh\u00eb n\u00ebse shtohet ky query-paramet\u00ebr n\u00eb k\u00ebrkes\u00eb?\u201d, \u201cn\u00eb cilat raste kthehet kodi 400?\u201d)<\/p>\n

Megjithat\u00eb, kur flitet p\u00ebr zhvillimin e nj\u00eb numri t\u00eb madh t\u00eb mikroservic\u00ebve, d\u00ebshirohet t\u00eb nxirret nj\u00eb p\u00ebrfitim shtes\u00eb nga annotimet e shkruara. P\u00ebr shembuj, n\u00eb baz\u00eb t\u00eb RAML\/SWAGGER mund t\u00eb gjenerohet nj\u00eb kod klienti dhe serveri n\u00eb nj\u00eb num\u00ebr t\u00eb madh gjuh\u00ebsh programuese. Po ashtu, mund t\u00eb gjenerohet automatikisht dokumentacioni p\u00ebr mikroservicin dhe t\u00eb ngarkohet n\u00eb portalin tuaj t\u00eb zhvilluesve :).<\/p>\n

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

Praktika e testimit t\u00eb mikroservic\u00ebve n\u00eb baz\u00eb t\u00eb p\u00ebrshkrimeve t\u00eb kontratave takohen m\u00eb rrall\u00eb. N\u00ebse keni shkruar si annotimin, ashtu edhe komponentin, mund t\u00eb krijoni nj\u00eb test automatik q\u00eb kontrollon adekuat\u00ebsin\u00eb e pun\u00ebs s\u00eb sh\u00ebrbimit me lloje t\u00eb ndryshme t\u00eb t\u00eb dh\u00ebnave n\u00eb hyrje. A kthen sh\u00ebrbimi ndonj\u00eb kod p\u00ebrgjigjie, i cili nuk \u00ebsht\u00eb p\u00ebrshkruar n\u00eb annotim? A do t\u00eb jet\u00eb n\u00eb gjendje t\u00eb procesoj\u00eb t\u00eb dh\u00ebnat e gabuara n\u00eb m\u00ebnyr\u00eb t\u00eb sakt\u00eb?<\/p>\n

P\u00ebr m\u00eb tep\u00ebr, realizimi cil\u00ebsor jo vet\u00ebm i kontratave, por edhe t\u00eb mjeteve p\u00ebr vizualizimin e annotimeve, lejon t\u00eb thjesht\u00ebsohet puna me mikroservicin. K\u00ebshtu, n\u00ebse arkitekti e p\u00ebrshkruan me cil\u00ebsi kontrat\u00ebn, mbi at\u00eb baz\u00eb dizajner\u00ebt dhe zhvilluesit do t\u00eb integrojn\u00eb sh\u00ebrbimin n\u00eb produkte t\u00eb tjera pa shpenzuar koh\u00eb shtes\u00eb.<\/p>\n

P\u00ebr pun\u00ebn e mjeteve t\u00eb tjera, si RAML ashtu edhe OAS kan\u00eb mund\u00ebsin\u00eb e shtimit t\u00eb metadatanave, t\u00eb cilat nuk parashihen nga standardi (p\u00ebr shembull, k\u00ebshtu b\u00ebhet n\u00eb OAS<\/a><\/noindex>).<\/p>\n

N\u00eb p\u00ebrgjith\u00ebsi, fusha p\u00ebr krijimtarin\u00eb n\u00eb aplikimin e kontratave p\u00ebr mikroservic\u00ebt \u00ebsht\u00eb e madhe... t\u00eb pakt\u00ebn n\u00eb teori<\/p>\n

Krahasoni nj\u00eb gjel me nj\u00eb asfalt<\/h3>\n

\nN\u00eb k\u00ebt\u00eb moment, drejtimi prioritar i zhvillimit n\u00eb Acronis \u00ebsht\u00eb p\u00ebrmir\u00ebsimi 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. Nd\u00ebrsa API-t\u00eb tona t\u00eb brendshme, t\u00eb p\u00ebrshkruara n\u00eb RAML, na k\u00ebnaqnin, nevoj\u00ebn p\u00ebr publikimin e API-r\u00ebve e rriti s\u00ebrish pyetjen: cili \u00ebsht\u00eb standardi m\u00eb i mir\u00eb i annotimeve p\u00ebr pun\u00ebn ton\u00eb?<\/p>\n

Fillimisht dukej se zgjidhjet ishin dy \u2014 jan\u00eb zhvillimet m\u00eb t\u00eb zakonshme RAML dhe Swagger (ose OAS). Por n\u00eb fakt doli se alternativat jan\u00eb t\u00eb pakt\u00ebn 2, por 3 ose m\u00eb shum\u00eb.<\/p>\n

N\u00eb nj\u00eb an\u00eb \u00ebsht\u00eb RAML - nj\u00eb gjuh\u00eb e fuqishme dhe efektive. Ajo implementon 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 - dometh\u00ebn\u00eb jo vet\u00ebm nj\u00eb produkt, por shum\u00eb mikrosh\u00ebrbime q\u00eb kan\u00eb pjes\u00eb t\u00eb p\u00ebrbashk\u00ebta t\u00eb kontratave - skemat e autentifikimit, llojet e t\u00eb dh\u00ebnave t\u00eb nj\u00ebjta, 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. P\u00ebr t\u00eb imagjinuar formatin e ngjarjes, imagjinoni se mbajt\u00ebsit e komponenteve kryesore t\u00eb Linux u larguan p\u00ebr t'u pun\u00ebsuar n\u00eb Microsoft. Nj\u00eb situat\u00eb e till\u00eb krijon parakushte p\u00ebr t\u00eb p\u00ebrdorur Swagger, i cili zhvillohet dinamik dhe n\u00eb versionin e tij t\u00eb tret\u00eb arrin praktikisht t\u00eb p\u00ebrmbush\u00eb RAML n\u00eb fleksibilitet dhe funksionalitet.<\/p>\n

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

\nSi\u00e7 rezulton, shum\u00eb nga mjetet open-source nuk jan\u00eb p\u00ebrdit\u00ebsuar n\u00eb versionin OAS 3.0. P\u00ebr mikrosh\u00ebrbimet n\u00eb Go, m\u00eb kritike do t\u00eb jet\u00eb mungesa e adaptimit t\u00eb go-swagger<\/a><\/noindex> n\u00eb versionin e ri t\u00eb standardit. Megjithat\u00eb, diferenca midis Swagger 2 dhe Swagger 3 \u00ebsht\u00eb e madhe.<\/a><\/noindex>P\u00ebr shembull, n\u00eb versionin e tret\u00eb zhvilluesit:<\/p>\n