{"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\/hu\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"Teh\u00e1t m\u00e9gis RAML vagy OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

A dinamikus mikroszervizek vil\u00e1g\u00e1ban b\u00e1rmi megv\u00e1ltozhat \u2013 b\u00e1rmely komponenst \u00e1t lehet \u00edrni m\u00e1s nyelven, k\u00fcl\u00f6nb\u00f6z\u0151 keretrendszereket \u00e9s architekt\u00far\u00e1kat haszn\u00e1lva. Csak a szerz\u0151d\u00e9seknek kell \u00e1lland\u00f3nak maradniuk, hogy a mikroszervizzel k\u00fcls\u0151leg folyamatosan lehetett interakci\u00f3ba l\u00e9pni, f\u00fcggetlen\u00fcl a bels\u0151 metamorf\u00f3zisokt\u00f3l. Ma arr\u00f3l fogunk besz\u00e9lni, hogy mi\u00e9rt neh\u00e9z a szerz\u0151d\u00e9sek le\u00edr\u00e1s\u00e1nak form\u00e1tum\u00e1t v\u00e1lasztani, \u00e9s megosztjuk a felfedezett artefaktumokat. <\/p>\n

\"Teh\u00e1t
\n<\/a><\/noindex>
\nA bejegyz\u00e9st k\u00e9sz\u00edtette Anna Melekhova<\/a><\/noindex> \u00e9s Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikroszervizek.<\/b> Az Acronis Cyber Cloud fejleszt\u00e9se sor\u00e1n r\u00e1j\u00f6tt\u00fcnk, hogy nem \u00e9lhet\u00fcnk n\u00e9lk\u00fcl\u00fck. A mikroszerviz tervez\u00e9se lehetetlen a szerz\u0151d\u00e9s formaliz\u00e1l\u00e1sa n\u00e9lk\u00fcl, amely a mikroszerviz interf\u00e9szek\u00e9nt funkcion\u00e1l.<\/p>\n

De amikor a term\u00e9k t\u00f6bb mint egy komponenst tartalmaz, \u00e9s a szerz\u0151d\u00e9s fejleszt\u00e9se rendszeres tev\u00e9kenys\u00e9gg\u00e9 v\u00e1lik, elker\u00fclhetetlen\u00fcl az optimaliz\u00e1l\u00e1si folyamaton kezdj\u00fck gondolkodni. Nyilv\u00e1nval\u00f3v\u00e1 v\u00e1lik, hogy az interf\u00e9sz (szerz\u0151d\u00e9s) \u00e9s az implement\u00e1ci\u00f3 (mikroszerviz) \u00f6sszhangban kell legyen egym\u00e1ssal, hogy a k\u00fcl\u00f6nb\u00f6z\u0151 komponenseknek ugyanazt a feladatot azonos m\u00f3don kell elv\u00e9gezni\u00fck, \u00e9s hogy a k\u00f6zpontos\u00edtott d\u00f6nt\u00e9shozatal n\u00e9lk\u00fcl minden csapatnak \u00fajra \u00e9s \u00fajra id\u0151t kell k\u00f6ltenie ezek megszerz\u00e9s\u00e9re. <\/p>\n

\"Teh\u00e1t
\nAz Amazon mikroszervizes architekt\u00far\u00e1ja tweetb\u0151l<\/a><\/noindex> Werner Vogels, az Amazon CTO-j\u00e1nak<\/i>
\nMi is a dilemma? De facto k\u00e9t m\u00f3don l\u00e9teznek a mikroszervizek k\u00f6z\u00f6tti interakci\u00f3k \u2013 HTTP Rest \u00e9s a Google \u00e1ltal kifejlesztett gRPC. A Google technol\u00f3giai stackj\u00e9be val\u00f3 bevon\u00f3d\u00e1s elker\u00fcl\u00e9se \u00e9rdek\u00e9ben a HTTP Rest mellett d\u00f6nt\u00f6tt\u00fcnk. A HTTP REST szerz\u0151d\u00e9sekhez val\u00f3 annot\u00e1ci\u00f3k \u00e1ltal\u00e1ban az al\u00e1bbi k\u00e9t form\u00e1tum egyik\u00e9ben tal\u00e1lhat\u00f3k: RAML \u00e9s OAS, amely kor\u00e1bban Swagger n\u00e9ven volt ismert. Ez\u00e9rt minden fejleszt\u0151csapatnak szembe kell n\u00e9znie azzal a sz\u00fcks\u00e9ggel, hogy v\u00e1lasszon az egyik szabv\u00e1ny mellett. De ahogy kider\u00fclt, ez a v\u00e1laszt\u00e1s nem mindig k\u00f6nny\u0171.<\/p>\n

Mi\u00e9rt van sz\u00fcks\u00e9g annot\u00e1ci\u00f3kra?<\/h3>\n

\nAz annot\u00e1ci\u00f3 arra szolg\u00e1l, hogy a k\u00fcls\u0151 felhaszn\u00e1l\u00f3 k\u00f6nnyen meg\u00e9rtse, mit lehet tenni a szolg\u00e1ltat\u00e1ssal a HTTP interf\u00e9sze r\u00e9v\u00e9n. Az alapvet\u0151 szinten az annot\u00e1ci\u00f3nak legal\u00e1bb az el\u00e9rhet\u0151 er\u0151forr\u00e1sok list\u00e1j\u00e1t, azok HTTP met\u00f3dusait, a k\u00e9r\u00e9s t\u00f6rzs\u00e9t, a param\u00e9terek felsorol\u00e1s\u00e1t, a sz\u00fcks\u00e9ges \u00e9s t\u00e1mogatott fejl\u00e9cek megjel\u00f6l\u00e9s\u00e9t, valamint a visszat\u00e9r\u00e9si k\u00f3dokat \u00e9s a v\u00e1laszform\u00e1tumokat kell tartalmaznia. Az annot\u00e1ci\u00f3s szerz\u0151d\u00e9s rendk\u00edv\u00fcl fontos eleme a sz\u00f3beli le\u00edr\u00e1suk is (\u201cmi t\u00f6rt\u00e9nik, ha ezt a query-param\u00e9tert hozz\u00e1adjuk a k\u00e9r\u00e9shez?\u201d, \u201cmikor t\u00e9r vissza a 400-as k\u00f3d?\u201d)<\/p>\n

Mindazon\u00e1ltal, amikor sok mikroszolg\u00e1ltat\u00e1s fejleszt\u00e9s\u00e9r\u0151l van sz\u00f3, \u00e9rdemes tov\u00e1bbi el\u0151ny\u00f6ket kinyerni az \u00edrt annot\u00e1ci\u00f3kb\u00f3l. P\u00e9ld\u00e1ul a RAML\/Swagger alapj\u00e1n gener\u00e1lhatunk kliens- \u00e9s szerveroldali k\u00f3dot sz\u00e1mos programoz\u00e1si nyelven. R\u00e1ad\u00e1sul automatikusan dokument\u00e1ci\u00f3t is kaphatunk a mikroszolg\u00e1ltat\u00e1sr\u00f3l, \u00e9s felt\u00f6lthetj\u00fck azt a fejleszt\u0151i port\u00e1lunkra :).<\/p>\n

\"Teh\u00e1t
\nA szerz\u0151d\u00e9s struktur\u00e1lt le\u00edr\u00e1s\u00e1nak p\u00e9ld\u00e1ja<\/i><\/p>\n

Ritk\u00e1bban tal\u00e1lkozni azzal a gyakorlattal, hogy mikroszolg\u00e1ltat\u00e1sokat tesztelnek a szerz\u0151d\u00e9sek le\u00edr\u00e1sai alapj\u00e1n. Ha \u00edrt\u00e1l annot\u00e1ci\u00f3t \u00e9s komponenst is, akkor l\u00e9trehozhatsz egy automatikus tesztet, amely ellen\u0151rzi a szolg\u00e1ltat\u00e1s megfelel\u0151 m\u0171k\u00f6d\u00e9s\u00e9t k\u00fcl\u00f6nb\u00f6z\u0151 t\u00edpus\u00fa bemeneti adatokkal. Visszaad-e a szolg\u00e1ltat\u00e1s olyan v\u00e1laszk\u00f3dot, amely nincs le\u00edrva az annot\u00e1ci\u00f3ban? K\u00e9pes-e helyesen kezelni a sz\u00e1nd\u00e9kosan hib\u00e1s adatokat?<\/p>\n

Tov\u00e1bb\u00e1, a szerz\u0151d\u00e9sek \u00e9s az annot\u00e1ci\u00f3k vizualiz\u00e1ci\u00f3s eszk\u00f6zeinek min\u0151s\u00e9gi megval\u00f3s\u00edt\u00e1sa lehet\u0151v\u00e9 teszi a mikroszolg\u00e1ltat\u00e1sokkal val\u00f3 munkav\u00e9gz\u00e9s egyszer\u0171s\u00edt\u00e9s\u00e9t. Teh\u00e1t, ha az \u00e9p\u00edt\u00e9sz megfelel\u0151en \u00edrta le a szerz\u0151d\u00e9st, akkor annak alapj\u00e1n a diz\u00e1jnerek \u00e9s a fejleszt\u0151k an\u00e9lk\u00fcl integr\u00e1lj\u00e1k a szolg\u00e1ltat\u00e1st m\u00e1s term\u00e9kekbe, hogy tov\u00e1bbi id\u0151r\u00e1ford\u00edt\u00e1sra lenne sz\u00fcks\u00e9g\u00fck.<\/p>\n

A RAML \u00e9s az OAS olyan lehet\u0151s\u00e9geket k\u00edn\u00e1l, amelyek lehet\u0151v\u00e9 teszik nem szabv\u00e1nyos metaadatok hozz\u00e1ad\u00e1s\u00e1t m\u00e1s eszk\u00f6z\u00f6k m\u0171k\u00f6d\u00e9s\u00e9hez (p\u00e9ld\u00e1ul, \u00edgy t\u00f6rt\u00e9nik az OAS-ban<\/a><\/noindex>).<\/p>\n

\u00d6sszess\u00e9g\u00e9ben a szerz\u0151d\u00e9sek mikroszolg\u00e1ltat\u00e1sokban val\u00f3 alkalmaz\u00e1s\u00e1ra hatalmas a kreativit\u00e1s ter\u00fclete... legal\u00e1bbis elm\u00e9letileg<\/p>\n

A s\u00fcndiszn\u00f3 \u00e9s a vipera \u00f6sszehasonl\u00edt\u00e1sa<\/h3>\n

\nJelenleg az Acronis fejleszt\u00e9si priorit\u00e1sa az Acronis Cyber Platform fejleszt\u00e9se. Az Acronis Cyber Platform \u00faj integr\u00e1ci\u00f3s pontokat ny\u00fajt harmadik f\u00e9lt\u0151l sz\u00e1rmaz\u00f3 szolg\u00e1ltat\u00e1soknak az Acronis Cyber Cloud \u00e9s az \u00fcgyn\u00f6ki r\u00e9szek k\u00f6z\u00f6tt. B\u00e1r a RAML-ben le\u00edrt bels\u0151 API-jaink megfeleltek, az API k\u00f6zz\u00e9t\u00e9tel\u00e9nek sz\u00fcks\u00e9gess\u00e9ge ism\u00e9t felvetette a k\u00e9rd\u00e9st: melyik annot\u00e1ci\u00f3s szabv\u00e1nyt \u00e9rdemes haszn\u00e1lni a munk\u00e1nkhoz?<\/p>\n

Kezdetben \u00fagy t\u0171nt, hogy k\u00e9t megold\u00e1s l\u00e9tezik - a legelterjedtebb RAML \u00e9s Swagger (vagy OAS). De val\u00f3j\u00e1ban kider\u00fclt, hogy legal\u00e1bb h\u00e1rom vagy ann\u00e1l t\u00f6bb alternat\u00edva l\u00e9tezik.<\/p>\n

Egyr\u00e9szt itt van a RAML - egy er\u0151s \u00e9s hat\u00e9kony nyelv. J\u00f3l megval\u00f3s\u00edtja a hierarchi\u00e1t \u00e9s az \u00f6r\u00f6kl\u0151d\u00e9st, \u00edgy ez a forma jobban megfelel a nagy v\u00e1llalatoknak, amelyeknek sok le\u00edr\u00e1sra van sz\u00fcks\u00e9g\u00fck - nem egy term\u00e9kre, hanem sok mikroszolg\u00e1ltat\u00e1sra, amelyek k\u00f6z\u00f6s szerz\u0151d\u00e9ses elemekkel rendelkeznek - autentik\u00e1ci\u00f3s s\u00e9m\u00e1k, azonos t\u00edpus\u00fa adatok, hib\u00e1k t\u00f6rzsei.<\/p>\n

De a RAML fejleszt\u0151je, a Mulesoft, csatlakozott az Open API konzorciumhoz, amely a fejl\u0151d\u00e9si lehet\u0151s\u00e9gekkel foglalkozik. Swagger<\/a><\/noindex>. Ez\u00e9rt a RAML le\u00e1ll\u00edtotta a fejl\u0151d\u00e9s\u00e9t. Ha elk\u00e9pzelj\u00fck az esem\u00e9ny form\u00e1tum\u00e1t, gondoljunk arra, hogy a Linux f\u0151 komponenseinek karbantart\u00f3i \u00e1tmentek dolgozni a Microsofthoz. Ez a helyzet kedvez a Swagger haszn\u00e1lat\u00e1nak, amely dinamikusan fejl\u0151dik, \u00e9s a leg\u00fajabb - harmadik verzi\u00f3j\u00e1ban - gyakorlatilag utol\u00e9ri a RAML-t rugalmass\u00e1g \u00e9s funkcion\u00e1lis szempontb\u00f3l.<\/p>\n

Ha nem lenne egy kis probl\u00e9ma...<\/h3>\n

\nKider\u00fclt, hogy nem minden open-source eszk\u00f6z friss\u00fclt az OAS 3.0 verzi\u00f3ra. A Go alap\u00fa mikroszolg\u00e1ltat\u00e1sok eset\u00e9ben a legkritikusabb a go-swagger<\/a><\/noindex> \u00faj szabv\u00e1ny friss\u00edt\u00e9s\u00e9nek hi\u00e1nya. Azonban a k\u00fcl\u00f6nbs\u00e9g a Swagger 2 \u00e9s Swagger 3 k\u00f6z\u00f6tt - \u00f3ri\u00e1si<\/a><\/noindex>. P\u00e9ld\u00e1ul, a harmadik verzi\u00f3ban a fejleszt\u0151k:<\/p>\n