તો શું તે RAML છે કે OAS (સ્વેગર)?

માઇક્રોસર્વિસિસની ગતિશીલ દુનિયામાં, કંઈપણ બદલાઈ શકે છે - કોઈપણ ઘટકને અલગ ભાષામાં, વિવિધ ફ્રેમવર્ક અને આર્કિટેક્ચરનો ઉપયોગ કરીને ફરીથી લખી શકાય છે. માત્ર કોન્ટ્રાક્ટ્સ યથાવત રહેવા જોઈએ જેથી આંતરિક મેટામોર્ફોસિસને ધ્યાનમાં લીધા વિના, કેટલાક કાયમી ધોરણે માઇક્રોસર્વિસ સાથે બહારથી સંપર્ક કરી શકાય. અને આજે આપણે કોન્ટ્રાક્ટનું વર્ણન કરવા માટે ફોર્મેટ પસંદ કરવાની અમારી સમસ્યા વિશે વાત કરીશું અને અમને મળેલી કલાકૃતિઓ શેર કરીશું.

પોસ્ટ તૈયાર અન્ના મેલેખોવા и વ્લાદિમીર લેપટિન

સૂક્ષ્મ સેવાઓ. એક્રોનિસ સાયબર ક્લાઉડનો વિકાસ કરતી વખતે, અમને સમજાયું કે અમે તેમાંથી છટકી શકતા નથી. અને કોન્ટ્રેક્ટને ઔપચારિક બનાવ્યા વિના માઇક્રોસર્વિસ ડિઝાઇન કરવી અશક્ય છે, જે માઇક્રોસર્વિસના ઇન્ટરફેસને રજૂ કરે છે.

પરંતુ જ્યારે ઉત્પાદનમાં એક કરતાં વધુ ઘટકો હોય છે, અને કરાર વિકાસ નિયમિત પ્રવૃત્તિ બની જાય છે, ત્યારે તમે મદદ કરી શકતા નથી પરંતુ પ્રક્રિયાના ઑપ્ટિમાઇઝેશન વિશે વિચારવાનું શરૂ કરી શકો છો. તે સ્પષ્ટ થઈ જાય છે કે ઈન્ટરફેસ (કરાર) અને અમલીકરણ (માઈક્રોસર્વિસ) એકબીજા સાથે મેળ ખાતા હોવા જોઈએ, વિવિધ ઘટકોએ સમાન વસ્તુઓ એક જ રીતે કરવી જોઈએ, અને આ બધા નિર્ણયોના કેન્દ્રિય નિર્ણય લીધા વિના, દરેક ટીમને ફરજ પાડવામાં આવશે તેમને મેળવવા માટે ફરીથી અને ફરીથી સમય પસાર કરો.

એમેઝોન માઇક્રોસર્વિસીસ ડાયાગ્રામ માંથી ચીંચીં કરવું વર્નર વોગેલિસ, સીટીઓ એમેઝોન
મૂંઝવણ શું છે? હકીકતમાં, માઇક્રોસર્વિસિસ સાથે ક્રિયાપ્રતિક્રિયા કરવાની બે રીતો છે - HTTP રેસ્ટ અને Google તરફથી gRPC. Google ના ટેક્નોલોજી સ્ટેકમાં ફસાઈ જવાની ઇચ્છા ન હોવાથી, અમે HTTP આરામ પસંદ કર્યો. HTTP REST કોન્ટ્રાક્ટ એનોટેશન્સ મોટાભાગે બેમાંથી એક ફોર્મેટમાં વર્ણવવામાં આવે છે: RAML અને OAS, જે અગાઉ સ્વેગર તરીકે ઓળખાતું હતું. તેથી, દરેક વિકાસ ટીમને ધોરણોમાંથી એક પસંદ કરવાની જરૂરિયાતનો સામનો કરવો પડે છે. પરંતુ જેમ તે બહાર આવ્યું છે, આ પસંદગી કરવી ખૂબ મુશ્કેલ હોઈ શકે છે.

ટીકાઓ શા માટે જરૂરી છે?

એનોટેશનની આવશ્યકતા છે જેથી બાહ્ય વપરાશકર્તા તેના HTTP ઇન્ટરફેસ દ્વારા તમારી સેવા સાથે શું કરી શકાય તે સરળતાથી શોધી શકે. એટલે કે, મૂળભૂત સ્તરે, એનોટેશનમાં ઉપલબ્ધ સંસાધનોની ઓછામાં ઓછી સૂચિ, તેમની HTTP પદ્ધતિઓ, વિનંતી સંસ્થાઓ, પરિમાણોની સૂચિ, જરૂરી અને સમર્થિત હેડરોનો સંકેત, તેમજ રીટર્ન કોડ્સ અને પ્રતિસાદ ફોર્મેટ હોવા આવશ્યક છે. કોન્ટ્રાક્ટ એનોટેશનનું અત્યંત મહત્વનું તત્વ એ તેમનું મૌખિક વર્ણન છે ("જો તમે વિનંતીમાં આ ક્વેરી પેરામીટર ઉમેરશો તો શું થશે?", "કયા કિસ્સામાં કોડ 400 પરત કરવામાં આવશે?")

જો કે, જ્યારે મોટી સંખ્યામાં માઇક્રોસર્વિસિસ વિકસાવવાની વાત આવે છે, ત્યારે તમે લેખિત ટીકાઓમાંથી વધારાનું મૂલ્ય કાઢવા માંગો છો. ઉદાહરણ તરીકે, RAML/Swagger પર આધારિત, તમે મોટી સંખ્યામાં પ્રોગ્રામિંગ ભાષાઓમાં ક્લાયંટ અને સર્વર કોડ બંને જનરેટ કરી શકો છો. તમે માઇક્રોસર્વિસ માટે આપમેળે દસ્તાવેજો પણ મેળવી શકો છો અને તેને તમારા ડેવલપર-પોર્ટલ પર અપલોડ કરી શકો છો :).

માળખાગત કરાર વર્ણનનું ઉદાહરણ

કોન્ટ્રેક્ટના વર્ણનના આધારે માઇક્રોસર્વિસિસનું પરીક્ષણ કરવાની પ્રથા ઓછી સામાન્ય છે. જો તમે એનોટેશન અને એક ઘટક બંને લખ્યું છે, તો પછી તમે એક ઓટોટેસ્ટ બનાવી શકો છો જે વિવિધ પ્રકારના ઇનપુટ ડેટા સાથે સેવાની પર્યાપ્તતાને તપાસે છે. શું સેવા એનોટેશનમાં વર્ણવેલ નથી તેવા પ્રતિભાવ કોડ પરત કરે છે? શું તે દેખીતી રીતે ખોટા ડેટા પર યોગ્ય રીતે પ્રક્રિયા કરવામાં સક્ષમ હશે?

તદુપરાંત, માત્ર કોન્ટ્રાક્ટ્સનું જ નહીં, પણ એનોટેશનને વિઝ્યુઅલાઈઝ કરવા માટેના ટૂલ્સનું ઉચ્ચ-ગુણવત્તાવાળા અમલીકરણ, માઇક્રોસર્વિસ સાથેના કાર્યને સરળ બનાવવાનું શક્ય બનાવે છે. એટલે કે, જો આર્કિટેક્ટ ઉચ્ચ-ગુણવત્તાવાળી રીતે કરારનું વર્ણન કરે છે, તેના આધારે, ડિઝાઇનર્સ અને વિકાસકર્તાઓ વધારાના સમય ખર્ચ વિના અન્ય ઉત્પાદનોમાં સેવાનો અમલ કરશે.

વધારાના સાધનોને સક્ષમ કરવા માટે, RAML અને OAS બંને પાસે મેટાડેટા ઉમેરવાની ક્ષમતા છે જે ધોરણ દ્વારા પ્રદાન કરવામાં આવી નથી (ઉદાહરણ તરીકે, આ રીતે તે OAS માં થાય છે).

સામાન્ય રીતે, માઇક્રોસર્વિસિસ માટે કોન્ટ્રાક્ટનો ઉપયોગ કરવામાં સર્જનાત્મકતાનો અવકાશ વિશાળ છે... ઓછામાં ઓછા સિદ્ધાંતમાં.

સાપ સાથે હેજહોગની સરખામણી

હાલમાં, એક્રોનિસ ખાતે પ્રાથમિક વિકાસ ક્ષેત્ર એ એક્રોનિસ સાયબર પ્લેટફોર્મનો વિકાસ છે. Acronis Cyber ​​Platform એ એક્રોનિસ સાયબર ક્લાઉડ અને એજન્ટ ભાગ સાથે તૃતીય-પક્ષ સેવાઓના એકીકરણના નવા મુદ્દા છે. જો કે અમે RAML માં વર્ણવેલ અમારા આંતરિક API થી ખુશ હતા, API ને પ્રકાશિત કરવાની જરૂરિયાતે ફરીથી પસંદગીનો પ્રશ્ન ઉભો કર્યો: અમારા કાર્ય માટે કયા એનોટેશન સ્ટાન્ડર્ડનો ઉપયોગ કરવો શ્રેષ્ઠ છે?

શરૂઆતમાં, એવું લાગતું હતું કે ત્યાં બે ઉકેલો છે - સૌથી સામાન્ય વિકાસ RAML અને Swagger (અથવા OAS) હતા. પરંતુ હકીકતમાં તે બહાર આવ્યું છે કે ત્યાં ઓછામાં ઓછા 2 વિકલ્પો નથી, પરંતુ 3 અથવા વધુ છે.

એક તરફ RAML છે - એક શક્તિશાળી અને કાર્યક્ષમ ભાષા. તે વંશવેલો અને વારસાને સારી રીતે અમલમાં મૂકે છે, તેથી આ ફોર્મેટ મોટી કંપનીઓ માટે વધુ યોગ્ય છે જેમને ઘણા બધા વર્ણનોની જરૂર હોય છે - એટલે કે, એક ઉત્પાદન નહીં, પરંતુ ઘણી માઇક્રોસેવાઓ જેમાં કરારના સામાન્ય ભાગો હોય છે - પ્રમાણીકરણ યોજનાઓ, સમાન ડેટા પ્રકારો, ભૂલ સંસ્થાઓ .

પરંતુ RAML ના ડેવલપર, મુલેસોફ્ટ, ઓપન API કન્સોર્ટિયમમાં જોડાયા છે, જે વિકાસ કરી રહ્યું છે. સ્વેગર. તેથી, RAML એ તેનો વિકાસ સ્થગિત કર્યો. ઇવેન્ટના ફોર્મેટની કલ્પના કરવા માટે, કલ્પના કરો કે મુખ્ય Linux ઘટકોના જાળવણીકારોએ Microsoft માટે કામ કરવાનું છોડી દીધું છે. આ પરિસ્થિતિ સ્વેગરનો ઉપયોગ કરવા માટેની પૂર્વજરૂરીયાતો બનાવે છે, જે ગતિશીલ રીતે વિકાસ કરી રહી છે અને નવીનતમ - ત્રીજા સંસ્કરણમાં - લવચીકતા અને કાર્યક્ષમતાના સંદર્ભમાં વ્યવહારીક રીતે RAML સાથે મેળ ખાય છે.

જો એક વસ્તુ માટે નહીં ...

તે બહાર આવ્યું છે તેમ, બધી ઓપન-સોર્સ યુટિલિટીઝને OAS 3.0 પર અપડેટ કરવામાં આવી નથી. ગોમાં માઇક્રોસર્વિસિસ માટે, સૌથી મહત્વપૂર્ણ બાબત અનુકૂલનનો અભાવ હશે ગો-સ્વેગર ધોરણના નવીનતમ સંસ્કરણ માટે. જો કે, સ્વેગર 2 અને સ્વેગર 3 વચ્ચેનો તફાવત છે વિશાળ. ઉદાહરણ તરીકે, ત્રીજા સંસ્કરણમાં વિકાસકર્તાઓ:

• પ્રમાણીકરણ યોજનાઓનું સુધારેલ વર્ણન
• સમાપ્ત JSON સ્કીમા સપોર્ટ
• ઉદાહરણો ઉમેરવાની ક્ષમતાને અપગ્રેડ કરી

પરિસ્થિતિ રમુજી છે: ધોરણ પસંદ કરતી વખતે, તમારે RAML, Swagger 2 અને Swagger 3 ને અલગ વિકલ્પો તરીકે ધ્યાનમાં લેવાની જરૂર છે. જો કે, માત્ર Swagger 2 પાસે ઓપનસોર્સ ટૂલ્સ માટે સારો સપોર્ટ છે. RAML ખૂબ જ લવચીક...અને જટિલ છે, અને Swagger 3 સમુદાય દ્વારા નબળી રીતે સપોર્ટેડ છે, તેથી તમારે માલિકીના સાધનો અથવા વ્યવસાયિક ઉકેલોનો ઉપયોગ કરવો પડશે, જે ખૂબ ખર્ચાળ હોય છે.

તદુપરાંત, જો સ્વેગરમાં ઘણી સરસ સુવિધાઓ છે, જેમ કે તૈયાર પોર્ટલ editor.swagger.io, જેના પર તમે એનોટેશન અપલોડ કરી શકો છો અને વિગતવાર વર્ણન, લિંક્સ અને કનેક્શન્સ સાથે તેનું વિઝ્યુલાઇઝેશન મેળવી શકો છો, તો પછી વધુ મૂળભૂત અને ઓછા મૈત્રીપૂર્ણ RAML માટે આવી કોઈ તક નથી. હા, તમે GitHub પરના પ્રોજેક્ટ્સમાં કંઈક શોધી શકો છો, ત્યાં એનાલોગ શોધી શકો છો અને તેને જાતે ગોઠવી શકો છો. જો કે, કોઈ પણ સંજોગોમાં, કોઈએ પોર્ટલ જાળવવું પડશે, જે મૂળભૂત ઉપયોગ અથવા પરીક્ષણ જરૂરિયાતો માટે એટલું અનુકૂળ નથી. વધુમાં, સ્વેગર વધુ "સિદ્ધાંતહીન" અથવા વધુ ઉદાર છે - તે કોડમાંની ટિપ્પણીઓમાંથી જનરેટ થઈ શકે છે, જે, અલબત્ત, API પ્રથમ સિદ્ધાંતની વિરુદ્ધ જાય છે અને કોઈપણ RAML ઉપયોગિતાઓ દ્વારા સમર્થિત નથી.

એક સમયે અમે વધુ લવચીક ભાષા તરીકે RAML સાથે કામ કરવાનું શરૂ કર્યું, અને પરિણામે અમારે ઘણું બધું જાતે કરવું પડ્યું. ઉદાહરણ તરીકે, એક પ્રોજેક્ટ ઉપયોગિતાનો ઉપયોગ કરે છે ramlfications એકમ પરીક્ષણોમાં, જે ફક્ત RAML 0.8 ને સપોર્ટ કરે છે. તેથી અમારે ક્રૉચ ઉમેરવાની હતી જેથી ઉપયોગિતા RAML સંસ્કરણ 1.0 ને “ખાઈ” શકે.

શું તમારે પસંદ કરવાની જરૂર છે?

RAML માટે ઉકેલોની ઇકોસિસ્ટમ પૂર્ણ કરવા પર કામ કર્યા પછી, અમે નિષ્કર્ષ પર આવ્યા કે અમારે RAML ને Swagger 2 માં રૂપાંતરિત કરવાની અને તેમાં તમામ ઓટોમેશન, ચકાસણી, પરીક્ષણ અને અનુગામી ઑપ્ટિમાઇઝેશન હાથ ધરવાની જરૂર છે. RAML ની ​​લવચીકતા અને Swagger તરફથી કમ્યુનિટી ટૂલિંગ સપોર્ટ બંનેનો લાભ લેવાનો આ એક સારો માર્ગ છે.

આ સમસ્યાને ઉકેલવા માટે, ત્યાં બે ઓપનસોર્સ ટૂલ્સ છે જે કરારમાં રૂપાંતર પ્રદાન કરવા જોઈએ:

1. oas-raml-કન્વર્ટર હાલમાં અસમર્થિત ઉપયોગિતા છે. તેની સાથે કામ કરતી વખતે, અમે શોધ્યું કે તેની પાસે જટિલ RAMLs સાથે ઘણી સમસ્યાઓ છે જે મોટી સંખ્યામાં ફાઇલો પર "ફેલાયા" છે. આ પ્રોગ્રામ JavaScript માં લખાયેલ છે અને સિન્ટેક્સ ટ્રીનું પુનરાવર્તિત ટ્રાવર્સલ કરે છે. ડાયનેમિક ટાઇપિંગને લીધે, આ કોડને સમજવો મુશ્કેલ બની જાય છે, તેથી અમે મૃત્યુ પામેલી ઉપયોગિતા માટે પેચ લખવામાં સમય ન બગાડવાનું નક્કી કર્યું.
2. વેબાપી-પાર્સર - એ જ કંપનીનું એક સાધન જે દાવો કરે છે કે તે કોઈપણ વસ્તુ અને દરેક વસ્તુને અને કોઈપણ દિશામાં કન્વર્ટ કરવા માટે તૈયાર છે. આજની તારીખે, RAML 0.8, RAML 1.0 અને સ્વેગર 2.0 માટે સમર્થન જાહેર કરવામાં આવ્યું છે. જો કે, અમારા સંશોધન સમયે, ઉપયોગિતા હજુ પણ હતી અત્યંત ભીના અને બિનઉપયોગી. વિકાસકર્તાઓ એક પ્રકારનું સર્જન કરે છે IR, તેમને ભવિષ્યમાં ઝડપથી નવા ધોરણો ઉમેરવાની મંજૂરી આપે છે. પરંતુ અત્યાર સુધી તે માત્ર કામ કરતું નથી.

અને તે બધી મુશ્કેલીઓ નથી જેનો અમે સામનો કર્યો. અમારી પાઇપલાઇનમાંનું એક પગલું એ ચકાસવાનું છે કે રિપોઝીટરીમાંથી RAML સ્પષ્ટીકરણની તુલનામાં યોગ્ય છે. અમે ઘણી ઉપયોગીતાઓનો પ્રયાસ કર્યો. આશ્ચર્યજનક રીતે, તેઓ બધાએ જુદા જુદા સ્થળોએ અને સંપૂર્ણપણે અલગ ખરાબ શબ્દો સાથે અમારી ટીકાઓ પર શપથ લીધા. અને હંમેશા મુદ્દા પર નહીં :).

અંતે, અમે હવે જૂના પ્રોજેક્ટ પર સ્થાયી થયા, જેમાં ઘણી સમસ્યાઓ પણ છે (કેટલીકવાર તે વાદળીમાંથી ક્રેશ થઈ જાય છે, નિયમિત અભિવ્યક્તિઓ સાથે કામ કરતી વખતે સમસ્યાઓ હોય છે). આમ, અમને મફત ટૂલ્સના આધારે માન્યતા અને રૂપાંતરણની સમસ્યાઓ હલ કરવાનો કોઈ રસ્તો મળ્યો ન હતો, અને વ્યાપારી ઉપયોગિતાનો ઉપયોગ કરવાનું નક્કી કર્યું. ભવિષ્યમાં, જેમ જેમ ઓપનસોર્સ ટૂલ્સ વધુ પરિપક્વ બનશે, તેમ આ સમસ્યા હલ કરવી વધુ સરળ બની શકે છે. તે દરમિયાન, "ફિનિશિંગ" માટે શ્રમ અને સમયનો ખર્ચ અમને વ્યવસાયિક સેવાના ખર્ચ કરતાં વધુ નોંધપાત્ર લાગતો હતો.

નિષ્કર્ષ

આ બધા પછી, અમે અમારો અનુભવ શેર કરવા માંગીએ છીએ અને નોંધવું છે કે કરારનું વર્ણન કરવા માટે કોઈ સાધન પસંદ કરતા પહેલા, તમારે સ્પષ્ટપણે વ્યાખ્યાયિત કરવાની જરૂર છે કે તમને તેમાંથી શું જોઈએ છે અને તમે કયા બજેટમાં રોકાણ કરવા તૈયાર છો. જો આપણે ઓપનસોર્સ વિશે ભૂલી જઈએ, તો ત્યાં પહેલેથી જ મોટી સંખ્યામાં સેવાઓ અને ઉત્પાદનો છે જે તમને તપાસવામાં, રૂપાંતરિત કરવામાં અને માન્ય કરવામાં મદદ કરશે. પરંતુ તેઓ ખર્ચાળ છે, અને ક્યારેક ખૂબ ખર્ચાળ છે. મોટી કંપની માટે આવા ખર્ચ સહન કરી શકાય છે, પરંતુ સ્ટાર્ટઅપ માટે તે મોટો બોજ બની શકે છે.

ટૂલ્સનો સેટ નક્કી કરો જેનો તમે પછીથી ઉપયોગ કરશો. ઉદાહરણ તરીકે, જો તમારે માત્ર કોન્ટ્રાક્ટ પ્રદર્શિત કરવાની જરૂર હોય, તો સ્વેગર 2 નો ઉપયોગ કરવો સરળ બનશે, જેમાં એક સુંદર API છે, કારણ કે RAML માં તમારે સેવા જાતે જ બનાવવી અને જાળવવી પડશે.
તમારી પાસે જેટલા વધુ કાર્યો હશે, ટૂલ્સની જરૂરિયાત જેટલી વિશાળ હશે, અને તે વિવિધ પ્લેટફોર્મ્સ માટે અલગ છે, અને ભવિષ્યમાં તમારા ખર્ચને ઓછો કરે તેવી પસંદગી કરવા માટે ઉપલબ્ધ સંસ્કરણોથી તરત જ પોતાને પરિચિત કરવું વધુ સારું છે.

પરંતુ તે ઓળખવા યોગ્ય છે કે આજે અસ્તિત્વમાં છે તે તમામ ઇકોસિસ્ટમ અપૂર્ણ છે. તેથી, જો કંપનીમાં એવા ચાહકો છે કે જેઓ RAML માં કામ કરવાનું પસંદ કરે છે કારણ કે "તે તમને વિચારોને વધુ લવચીક રીતે વ્યક્ત કરવાની મંજૂરી આપે છે," અથવા, તેનાથી વિપરીત, સ્વેગર પસંદ કરે છે કારણ કે "તે સ્પષ્ટ છે," તેમને કામ કરવા માટે છોડી દેવાનું શ્રેષ્ઠ છે. તેઓ જે છે તેમાં તેઓ તેનો ઉપયોગ કરે છે અને તે ઇચ્છે છે, કારણ કે કોઈપણ ફોર્મેટના ટૂલ્સને ફાઇલ સાથે ફેરફારની જરૂર હોય છે.

અમારા અનુભવની વાત કરીએ તો, નીચેની પોસ્ટ્સમાં અમે અમારા RAML-Swagger આર્કિટેક્ચરના આધારે અમે કયા સ્ટેટિક અને ડાયનેમિક ચેક્સ હાથ ધરીએ છીએ તે વિશે વાત કરીશું, તેમજ અમે કોન્ટ્રાક્ટમાંથી કયા દસ્તાવેજો જનરેટ કરીએ છીએ અને તે બધું કેવી રીતે કાર્ય કરે છે.

ફક્ત નોંધાયેલા વપરાશકર્તાઓ જ સર્વેમાં ભાગ લઈ શકે છે. સાઇન ઇન કરો, મહેરબાની કરીને.

માઇક્રોસર્વિસ કોન્ટ્રાક્ટની ટીકા કરવા માટે તમે કઈ ભાષાનો ઉપયોગ કરો છો?

• RAML 0.8

• RAML 1.0

• સ્વેગર 2

• OAS3 (ઉર્ફ)

• બ્લુપ્રિન્ટ

• અન્ય

• ઉપયોગ કરતા નથી

100 વપરાશકર્તાઓએ મત ​​આપ્યો. 24 વપરાશકર્તાઓ દૂર રહ્યા.

સોર્સ: www.habr.com