ስለዚህ RAML ነው ወይስ OAS (Swagger)?

በማይክሮ ሰርቪስ ተለዋዋጭ ዓለም ውስጥ ማንኛውም ነገር ሊለወጥ ይችላል-ማንኛውም አካል በተለያዩ ማዕቀፎች እና አርክቴክቸር በመጠቀም በሌላ ቋንቋ እንደገና ሊፃፍ ይችላል። ኮንትራቶች ብቻ ሳይለወጡ መቆየት አለባቸው ማይክሮ ሰርቪሱ ከውስጥ ጋር ምንም ይሁን ምን በተወሰነ ቋሚነት ከውጭ ጋር መስተጋብር መፍጠር ይቻላል. እና ዛሬ ስለ ኮንትራቶች መግለጫ ቅርጸት ስለመምረጥ ችግራችን እንነጋገራለን እና ያገኘናቸውን ቅርሶች እናካፍላለን።

ፖስት ተዘጋጅቷል። አና መለኮቫ и ቭላድሚር ላፓቲን

የማይክሮ አገልግሎቶች አክሮኒስ ሳይበር ክላውድ ስናዳብር ከነሱ ማምለጥ እንደማንችል ተገነዘብን። እና ማይክሮ ሰርቪስ መንደፍ የማይክሮ ሰርቪሱን በይነገጽ የሚወክለው ኮንትራቱን መደበኛ ካልሆነ የማይቻል ነው።

ነገር ግን አንድ ምርት ከአንድ በላይ አካላትን ሲይዝ፣ እና የኮንትራት ልማት መደበኛ ስራ ከሆነ፣ ስለ ሂደት ማመቻቸት ማሰብ መጀመር አይችሉም። በይነገጽ (ኮንትራት) እና አተገባበር (ማይክሮ ሰርቪስ) እርስ በርስ መጣጣም እንዳለባቸው ግልጽ ይሆናል, የተለያዩ አካላት ተመሳሳይ ነገሮችን በተመሳሳይ መንገድ ማከናወን እንዳለባቸው እና እነዚህ ሁሉ ውሳኔዎች የተማከለ ውሳኔ ከሌለ እያንዳንዱ ቡድን እንዲገደድ ይገደዳል. እነሱን ለማግኘት ብዙ ጊዜ ያሳልፉ .

የአማዞን ማይክሮ ሰርቪስ ንድፍ ከ ትዊተር ቨርነር Vogelis, CTO አማዞን
አጣብቂኝ ምንድን ነው? እንደ እውነቱ ከሆነ፣ የማይክሮ አገልግሎቶችን ለመገናኘት ሁለት መንገዶች አሉ - HTTP Rest እና gRPC ከGoogle። በGoogle የቴክኖሎጂ ቁልል ውስጥ ለመጠመድ ስላልፈለግን HTTP እረፍትን መርጠናል ። የኤችቲቲፒ REST ውል ማብራሪያዎች ብዙውን ጊዜ ከሁለት ቅርፀቶች በአንዱ ይገለፃሉ፡ RAML እና OAS፣ ቀደም ሲል ስዋገር ይባላሉ።ስለዚህ እያንዳንዱ የእድገት ቡድን ከመመዘኛዎቹ አንዱን የመምረጥ አስፈላጊነት ይገጥመዋል። ግን እንደ ተለወጠ, ይህንን ምርጫ ማድረግ በጣም ከባድ ሊሆን ይችላል.

ማብራሪያዎች ለምን ያስፈልጋሉ?

ማብራሪያው የሚያስፈልገው የውጭ ተጠቃሚ በኤችቲቲፒ በይነገጽ በኩል በአገልግሎትዎ ምን ሊደረግ እንደሚችል በቀላሉ ለማወቅ እንዲችል ነው። ይኸውም፣ በመሠረታዊ ደረጃ፣ ማብራሪያው ቢያንስ የሚገኙ ሀብቶች ዝርዝር፣ የኤችቲቲፒ ስልቶቻቸው፣ የጥያቄ አካላት፣ የመለኪያዎች ዝርዝር፣ የሚፈለጉትን እና የሚደገፉ አርዕስቶችን እንዲሁም የመመለሻ ኮዶችን እና የምላሽ ቅርጸቶችን መያዝ አለበት። የኮንትራቱ ማብራሪያ እጅግ በጣም አስፈላጊ አካል የቃል ገለፃቸው ነው ("ይህን መጠይቅ በጥያቄው ላይ ካከሉ ምን ይሆናል?"፣ "በምን አይነት ሁኔታ ኮድ 400 ይመለሳል?")

ነገር ግን፣ ብዙ ቁጥር ያላቸውን ማይክሮ ሰርቪስ ለማዳበር በሚያስፈልግበት ጊዜ፣ ከተጻፉት ማብራሪያዎች ተጨማሪ እሴት ማውጣት ትፈልጋለህ። ለምሳሌ፣ RAML/Swagger ላይ በመመስረት፣ ሁለቱንም የደንበኛ እና የአገልጋይ ኮድ በብዙ የፕሮግራሚንግ ቋንቋዎች ማመንጨት ይችላሉ። እንዲሁም ለማይክሮ አገልግሎት ሰነዶችን በራስ ሰር ተቀብለው ወደ ገንቢ-ፖርታልዎ መስቀል ይችላሉ :)

የተዋቀረ የውል መግለጫ ምሳሌ

ብዙም ያልተለመደው በኮንትራት መግለጫዎች ላይ በመመርኮዝ የማይክሮ አገልግሎቶችን የመሞከር ልምምድ ነው። ሁለቱንም ማብራሪያ እና አንድ አካል ከጻፉ የአገልግሎቱን በቂነት በተለያዩ የግብዓት ውሂብ የሚፈትሽ አውቶማቲክ መፍጠር ይችላሉ። አገልግሎቱ በማብራሪያው ውስጥ ያልተገለፀውን የምላሽ ኮድ ይመልሳል? ግልጽ ያልሆነ ውሂብ በትክክል ማካሄድ ይችል ይሆን?

ከዚህም በላይ ከፍተኛ ጥራት ያለው ትግበራ ኮንትራቶች እራሳቸው ብቻ ሳይሆን ማብራሪያዎችን ለማየት የሚረዱ መሳሪያዎችም ስራውን በማይክሮ ሰርቪስ ቀላል ለማድረግ ያስችላል. ማለትም አርክቴክቱ ውሉን በጥራት ከገለፀው በእሱ ላይ ተመስርተው ዲዛይነሮች እና ገንቢዎች አገልግሎቱን ያለ ተጨማሪ ጊዜ ወጪ በሌሎች ምርቶች ላይ ተግባራዊ ያደርጋሉ።

ተጨማሪ መሳሪያዎችን ለማንቃት ሁለቱም RAML እና OAS በመደበኛው ያልተሰጠ ሜታዳታ የመጨመር ችሎታ አላቸው (ለምሳሌ በ OAS ውስጥ የሚደረገው ይህ ነው).

በአጠቃላይ፣ ለማይክሮ አገልግሎት ኮንትራቶች የመጠቀም ለፈጠራ ያለው ወሰን ትልቅ ነው...ቢያንስ በንድፈ ሐሳብ ደረጃ።

ጃርትን ከእባብ ጋር ማወዳደር

በአሁኑ ጊዜ በአክሮኒስ ውስጥ ቅድሚያ የሚሰጠው የልማት ቦታ የአክሮኒስ ሳይበር ፕላትፎርም ልማት ነው። አክሮኒስ ሳይበር ፕላትፎርም የሶስተኛ ወገን አገልግሎቶች ከአክሮኒስ ሳይበር ክላውድ እና ከወኪሉ አካል ጋር አዲስ የውህደት ነጥብ ነው። በ RAML ውስጥ በተገለጹት የውስጥ ኤፒአይዎቻችን ደስተኛ ብንሆንም፣ ኤፒአይን እንደገና የማተም አስፈላጊነት የምርጫውን ጥያቄ አስነስቷል፡ የትኛውን የማብራሪያ መስፈርት ለስራችን መጠቀም የተሻለ ነው?

በመጀመሪያ ፣ ሁለት መፍትሄዎች ያሉ ይመስላሉ - በጣም የተለመዱት እድገቶች RAML እና Swagger (ወይም OAS) ናቸው። ግን በእውነቱ ቢያንስ 2 አማራጮች የሉም ፣ ግን 3 ወይም ከዚያ በላይ።

በአንድ በኩል RAML አለ - ኃይለኛ እና ቀልጣፋ ቋንቋ. ተዋረድን እና ውርስን በደንብ ይተገብራል ፣ ስለሆነም ይህ ቅርጸት ብዙ መግለጫዎችን ለሚያስፈልጋቸው ትላልቅ ኩባንያዎች የበለጠ ተስማሚ ነው - ማለትም አንድ ምርት አይደለም ፣ ግን ብዙ የኮንትራቶች ክፍሎች ያሉት ብዙ ማይክሮ ሰርቪስ - የማረጋገጫ እቅዶች ፣ ተመሳሳይ የውሂብ ዓይነቶች ፣ የስህተት አካላት። .

ነገር ግን የ RAML ገንቢ ሙሌሶፍት በማደግ ላይ ያለውን የOpen API consortium ተቀላቅሏል። ተንሸራታች. ስለዚህ RAML እድገቱን አቁሟል። የዝግጅቱን ቅርጸት ለመገመት የዋናዎቹ የሊኑክስ ክፍሎች ጠባቂዎች በማይክሮሶፍት ውስጥ ለመስራት እንደቀሩ አስቡት። ይህ ሁኔታ በተለዋዋጭ እና በቅርብ ጊዜ - በሶስተኛ ስሪት - በተለዋዋጭነት እና በተግባራዊነት ከ RAML ጋር የሚጣጣም Swaggerን ለመጠቀም ቅድመ ሁኔታዎችን ይፈጥራል።

ለአንድ ነገር ካልሆነ...

እንደ ተለወጠ፣ ሁሉም ክፍት ምንጭ መገልገያዎች ወደ OAS 3.0 አልተዘመኑም። በ Go ውስጥ ለሚገኙ ማይክሮ ሰርቪስ, በጣም ወሳኙ ነገር የማመቻቸት እጥረት ይሆናል ሂድ-swagger ለደረጃው የቅርብ ጊዜ ስሪት። ሆኖም በ Swagger 2 እና Swagger 3 መካከል ያለው ልዩነት ነው። ግዙፍ. ለምሳሌ፣ በሶስተኛው ስሪት ውስጥ ገንቢዎቹ፡-

• የተሻሻለ የማረጋገጫ እቅዶች መግለጫ
• አልቋል JSON የመርሃግብር ድጋፍ
• ምሳሌዎችን የመጨመር ችሎታን አሻሽሏል።

ሁኔታው አስቂኝ ነው: ደረጃን በሚመርጡበት ጊዜ RAML, Swagger 2 እና Swagger 3 እንደ የተለየ አማራጮች ግምት ውስጥ ማስገባት አለብዎት. ሆኖም፣ ለOpenSource መሳሪያዎች ጥሩ ድጋፍ ያለው Swagger 2 ብቻ ነው። RAML በጣም ተለዋዋጭ ነው...እና ውስብስብ ነው፣ እና Swagger 3 በማህበረሰብ በደንብ አይደገፍም፣ ስለዚህ በጣም ውድ የሆኑ የባለቤትነት መሳሪያዎችን ወይም የንግድ መፍትሄዎችን መጠቀም አለቦት።

በተጨማሪም ፣ በ Swagger ውስጥ ብዙ ጥሩ ባህሪዎች ካሉ ፣ ለምሳሌ ዝግጁ-የተሰራ ፖርታል አርታዒ.swagger.io, ማብራሪያ መስቀል የሚችሉበት እና ምስሉን ከዝርዝር መግለጫ፣ አገናኞች እና ግንኙነቶች ጋር ማግኘት የምትችልበት፣ ከዚያ ለበለጠ መሠረታዊ እና ወዳጃዊ ያልሆነ RAML እንደዚህ ያለ እድል የለም። አዎ፣ በ GitHub ላይ ካሉ ፕሮጀክቶች መካከል የሆነ ነገር መፈለግ፣ አናሎግ እዚያ ማግኘት እና እራስዎ ማሰማራት ይችላሉ። ይሁን እንጂ በማንኛውም ሁኔታ አንድ ሰው ፖርታልን መጠበቅ ይኖርበታል, ይህም ለመሠረታዊ አጠቃቀም ወይም ለሙከራ ፍላጎቶች በጣም ምቹ አይደለም. በተጨማሪም ፣ swagger የበለጠ “መርህ የለሽ” ፣ ወይም የበለጠ ሊበራል - በኮዱ ውስጥ ካሉ አስተያየቶች ሊመነጭ ይችላል ፣ እሱ በእርግጥ ፣ ከኤፒአይ የመጀመሪያ መርህ ጋር የሚቃረን እና በማንኛውም የ RAML መገልገያዎች አይደገፍም።

በአንድ ወቅት ከ RAML ጋር እንደ ተለዋዋጭ ቋንቋ መስራት ጀመርን, በዚህም ምክንያት እኛ እራሳችን ብዙ ነገሮችን ማድረግ ነበረብን. ለምሳሌ, ከፕሮጀክቶቹ ውስጥ አንዱ መገልገያውን ይጠቀማል ramfications RAML 0.8 ን ብቻ የሚደግፍ በክፍል ሙከራዎች ውስጥ። ስለዚህ መገልገያው RAML ስሪት 1.0 "መብላት" እንዲችል ክራንች መጨመር ነበረብን.

መምረጥ ያስፈልግዎታል?

ለ RAML የመፍትሄ ሃሳቦችን ስነ-ምህዳር በማጠናቀቅ ላይ ከሰራን በኋላ, RAML ን ወደ Swagger 2 መለወጥ እና ሁሉንም አውቶማቲክ, ማረጋገጫ, ሙከራ እና ቀጣይ ማመቻቸት ማካሄድ አለብን ወደሚል መደምደሚያ ላይ ደርሰናል. ይህ ሁለቱንም የ RAML ተለዋዋጭነት እና ከስዋገር የሚገኘውን የማህበረሰብ መሳሪያ ድጋፍ ለመጠቀም ጥሩ መንገድ ነው።

ይህንን ችግር ለመፍታት የኮንትራት ልወጣን የሚያቀርቡ ሁለት የOpenSource መሳሪያዎች አሉ፡

1. oas-raml-መቀየሪያ በአሁኑ ጊዜ የማይደገፍ መገልገያ ነው። ከእሱ ጋር እየሠራን ሳለ በበርካታ ፋይሎች ላይ "የተበተኑ" ውስብስብ RAML ዎች ላይ በርካታ ችግሮች እንዳሉት ደርሰንበታል. ይህ ፕሮግራም በጃቫ ስክሪፕት የተፃፈ ሲሆን የአገባብ ዛፍ ተደጋጋሚ ጉዞን ያከናውናል። በተለዋዋጭ ትየባ ምክንያት፣ ይህን ኮድ ለመረዳት አስቸጋሪ ይሆናል፣ ስለዚህ እየሞተ ላለው መገልገያ ጥገና ለመጻፍ ጊዜ ላለማባከን ወስነናል።
2. webapi-parser - ማንኛውንም ነገር እና ሁሉንም ነገር ለመለወጥ ዝግጁ ነኝ ከሚል ከተመሳሳይ ኩባንያ የመጣ መሳሪያ እና በማንኛውም አቅጣጫ። እስካሁን ድረስ ለ RAML 0.8፣ RAML 1.0 እና Swagger 2.0 ድጋፍ ይፋ ተደርጓል። ነገር ግን, በምርምርዎቻችን ጊዜ, መገልገያው አሁንም ነበር እጅግ በጣም እርጥብ እና ጥቅም ላይ የማይውል. ገንቢዎች አንድ ዓይነት ይፈጥራሉ IR, ወደፊት አዳዲስ ደረጃዎችን በፍጥነት እንዲጨምሩ ያስችላቸዋል. ግን እስካሁን ድረስ አይሰራም።

እና ያጋጠሙን ሁሉም ችግሮች አይደሉም. በቧንቧችን ውስጥ ካሉት እርምጃዎች አንዱ RAML ከማከማቻው ውስጥ ካለው ዝርዝር ሁኔታ አንጻር ትክክለኛ መሆኑን ማረጋገጥ ነው። በርካታ መገልገያዎችን ሞክረናል። የሚገርመው ግን ሁሉም በየቦታው እና ሙሉ ለሙሉ በተለያየ መጥፎ ቃላቶች ማብራሪያዎቻችንን ተሳለሉ። እና ሁልጊዜ ወደ ነጥቡ አይደለም :).

በመጨረሻ ፣ አሁን ያለፈበት ፕሮጀክት ላይ ተቀመጥን ፣ እሱም እንዲሁ በርካታ ችግሮች አሉት (አንዳንድ ጊዜ ከሰማያዊው ውጭ ይወድቃል ፣ በመደበኛ መግለጫዎች ሲሰራ ችግር አለበት)። ስለዚህ በነጻ መሳሪያዎች ላይ በመመስረት የማረጋገጫ እና የመለወጥ ችግሮችን ለመፍታት የሚያስችል መንገድ አላገኘንም, እና የንግድ መገልገያ ለመጠቀም ወሰንን. ወደፊት፣ የOpenSource መሳሪያዎች ይበልጥ እየበሰሉ ሲሄዱ፣ ይህ ችግር ለመፍታት ቀላል ይሆናል። እስከዚያው ድረስ፣ “ለመጨረስ” የሚከፈለው የጉልበትና የጊዜ ወጪ ከንግድ አገልግሎት ዋጋ የበለጠ ጉልህ ሆኖ ታየን።

መደምደሚያ

ከዚህ ሁሉ በኋላ የእኛን ልምድ ለማካፈል እና ኮንትራቶችን ለመግለፅ መሳሪያ ከመምረጥዎ በፊት ከእሱ ምን እንደሚፈልጉ እና የትኛውን በጀት ለመዋዕለ ንዋይ ለማፍሰስ እንደሚፈልጉ በግልፅ መግለፅ ያስፈልግዎታል. ስለ OpenSource ከረሳን ለመፈተሽ፣ ለመለወጥ እና ለማረጋገጥ የሚረዱዎት ብዙ ቁጥር ያላቸው አገልግሎቶች እና ምርቶች አሉ። ግን ውድ ናቸው, እና አንዳንድ ጊዜ በጣም ውድ ናቸው. ለትልቅ ኩባንያ, እንደዚህ አይነት ወጪዎች ይቋቋማሉ, ነገር ግን ለጀማሪ ትልቅ ሸክም ሊሆኑ ይችላሉ.

በኋላ ላይ የሚጠቀሙባቸውን የመሳሪያዎች ስብስብ ይወስኑ. ለምሳሌ ኮንትራት ማሳየት ብቻ ካስፈለገዎት ውብ ኤፒአይ ያለውን Swagger 2 መጠቀም ቀላል ይሆናል ምክንያቱም በ RAML ውስጥ አገልግሎቱን እራስዎ መገንባት እና ማቆየት አለብዎት።
ብዙ ተግባራት ሲኖሩዎት, የመሳሪያዎች ፍላጎት ሰፊ ይሆናል, እና ለተለያዩ የመሳሪያ ስርዓቶች የተለያዩ ናቸው, እና ለወደፊቱ ወጪዎችዎን የሚቀንስ ምርጫ ለማድረግ እራስዎን ከሚገኙ ስሪቶች ጋር ወዲያውኑ ማወቅ የተሻለ ነው.

ግን ዛሬ ያሉት ሁሉም ሥነ-ምህዳሮች ፍጽምና የጎደላቸው መሆናቸውን መገንዘብ ተገቢ ነው። ስለዚህ, በኩባንያው ውስጥ በ RAML ውስጥ ለመስራት የሚወዱ ደጋፊዎች ካሉ "ሀሳቦችን በተለዋዋጭነት እንዲገልጹ ያስችልዎታል" ወይም በተቃራኒው ስዋገርን ይመርጣሉ ምክንያቱም "ይበልጥ ግልጽ ነው" ወደ ሥራ መተው ይሻላል. በየትኛዉም እነሱ ጥቅም ላይ ውለዋል እና ይፈልጋሉ፣ ምክንያቱም የማንኛውም ቅርጸቶች መሳሪያዎች በፋይል ማሻሻያ ያስፈልጋቸዋል።

የእኛን ልምድ በተመለከተ፣ በሚቀጥሉት ጽሁፎች በእኛ RAML-Swagger ስነ-ህንፃ ላይ ተመስርተን ምን አይነት የማይለዋወጡ እና ተለዋዋጭ ቼኮች እንነጋገራለን፣ እንዲሁም ከኮንትራቶች ምን ሰነዶች እንደምናመነጭ እና ሁሉም እንዴት እንደሚሰራ እንነጋገራለን።

በዳሰሳ ጥናቱ ውስጥ የተመዘገቡ ተጠቃሚዎች ብቻ መሳተፍ ይችላሉ። ስግን እንእባክህን።

የማይክሮ አገልግሎት ውሎችን ለማብራራት ምን ቋንቋ ይጠቀማሉ?

• RAML 0.8

• RAML 1.0

• ስዋገር 2

• OAS3 (በሚታወቀው)

• የብሉቱዝ

• ሌላ

• አለመጠቀም

100 ተጠቃሚዎች ድምጽ ሰጥተዋል። 24 ተጠቃሚዎች ድምፀ ተአቅቦ አድርገዋል።

ምንጭ: hab.com