Swagger nima va nima uchun bu muhim?
1800-yillarning boshlarida, Amerikada barcha yo’lovchilar uchun temir yo’l xizmati bepul bo’lgan. Har bir shaharda vaqt ko’rsatkichi turlicha bo’lib, Amerikaning o’zida 300 dan ortiq turli vaqt zonalari mavjuddir. Bu poyezdlar jadvalini muvofiqlashtirishni juda qiyinlashtirardi va uzoq safarlarni rejalashtirish deyarli imkonsiz edi.
Poyezdlar transportning mashhur usuli bo’lgan bir paytda, poyezdlar qatnovida ushbu jarayon muqarrar muammo tug’dirdi. Muammoning yagona yechimi vaqt mintaqalarini hisobga olgan holda, barcha Amerika temir yo’llari uchun sanoat standartini yaratish edi. Natijada, temir yo’llar butun dunyoni bog’lab, sanoat inqilobiga yordam berdi.
Millionlab odamlar muloqot qilishi uchun umumiy lug’at bo’lishi kerak
Dasturiy ta’minot sanoatida API manzili ham shunga o’xshash muammoga duch kelmoqda. Bugungi kunning barcha zamonaviy tijorat sohasida dasturlash kodlari muhim ahamiyatga ega bo’lib, ma’lumotlarga ulanish va tarqatishning eng samarali uslubi bu API orqali sodir bo’ladi. Ammo nafaqat API-larni loyihalash uchun sanoat standarti mavjud, balki ularni hujjatlashtirish uchun sanoat standarti ham mavjud emas.
APIlar muhandislarga o’zaro bog’lanishlari va o’z ishlanmalar bilan o’rtoqlashishlariga imkon berishi lozim. APIlar Twilio singari kompaniyalarga boshqa korxona mahsulotlarga qo’shimcha qo’shishga va umumiy bilimlarning ekotizimini yaratishga imkon beradi. Ammo APIlar qachon ulardan foydalanish mumkin bo’lgandagina qiymatga ega bo’lib, buning uchun u tushunarli qo’llanilish hujattiga ega bo’lishi talab etiladi.
Noaniq hujjatlar noto’g’ri vaqtni ko’rsatadigan soat kabi foydasizdir. Shunday qilib mutaxassislar APIga oid bo’lgan tushuncha va izohlarni standartlashirish uchun juda qattiq mehnat qilishdi. Shu yerda biz bevosita Swagger atamasiga duch kelamiz. Swagger bu APIlardan semantik ravishda foydalanish uchun ishlatiladigan qoidalar va vositalar to’plamidir. Umuman olganda, Swagger bu barchani bir sahifaga birlashtiruvchi agnostik til vositasi hisoblanadi.
Swagger haqida
Qisqacha aytganda Swagger («Ochiq API tashabbuskori») — sizning API tushunchangizni hamma tushunadigan umumiy til yordamida tasvirlash vositasidir. Ushbu tushunchani uy uchun loyiha deb qabul qiling. Siz o’zingiz xohlagan qurilish materiallaridan foydalanishingiz mumkin, ammo siz rejalashtirilgan parametrlaridan tashqariga chiqolmaysiz. APIlar uchun RAML, APIBlueprint va Sum Summent kabi mashhurlikka erishgan boshqa mavjud arxitekturalar mavjud. Lekin Swagger tushunarli hujjat tashkillashtirish bilan birga foydalanuvchiga yuqoridagilarga nisbatan ko’proq manfaat keltiradi.
Bu ishlab chiqaruvchilar va ishlab chiqarmaydiganlar uchun bir xil darajada tushunarli.
Mahsulot menejerlari, sheriklar va hatto potentsial mijozlar API dizayniga kirishlari mumkin, chunki ular ushbu do’stona interfeys interfeysida aniq joylashtirilganligini ko’rishlari mumkin.
Bu inson va mashina tomonidan o’qiy olish imkoniyati.
Bu shuni anglatadiki, bu nafaqat sizning guruhingiz bilan birgalikda baham ko’rilishi, balki bir xil hujjatlar API-ga bog’liq jarayonlarni avtomatlashtirish uchun ham ishlatilishi mumkin.
Bu oson sozlanishi.
Bu API muammolarini sinab ko’rish va ularni bartaraf etishning qulay imkoniyati.
Ushbu uchta imtiyoz nafaqat ishlab chiqaruvchilarning hayotini osonlashtiradi, balki ular API yanada iste’molni yanada rivojlanishiga turtki bo’ladi. Swagger spetsifikatsiyasidan foydalangan har qanday APIni o’qish, qayta ishlash va foydalanish juda osondir. Shuning uchun ham Netflix, Akana va Yelp kabi yirik kompaniyalar allaqachon Swagger poyezdida o’z biznes sayohatlarini olib borishmoqda.
Birinchi dizaynga asoslangan APIning rivojlanishi
Swaggerdan foydalanishning ikkita asosiy usuli mavjud:
—Top-down approach, or design-first (yuqoridan-pastga yoki dizayn-birinchi) Bu shuni anglatadiki, siz biron-bir kodni yozmasdan oldin o’zingizning API-ni loyihalash maqsadida Swaggerga murojaat qilasiz.
— Bottom-up approach, or code-first (Pastdan yuqoriga yoki yondosh kod) Bu sizning API uchun kodni allaqachon yozganingizni anglatadi va siz APIni hujjatlashtirish uchun Swaggerdan foydalanasiz.
Dastlabki vaqtlari, birinchi bo’lib APIlar yaratilishi juda ommalashgan edi. Bu juda oson, chunki siz borganingizda sozlashlarni amalga oshirishingiz mumkin va u Agile etkazib berish jarayoniga juda mos keladi. Ammo siz dizayn haqida o’ylamaganingiz sababli, bu tushunish va hujjatlashtirish qiyin bo’lgan API uchun yaratishi mumkin. Tushunarli, o’qilishi oson bo’lgan hujjatlarni rasmiylashtirish birinchi uslubdan foydalanishni ommalashtirdi. Hujjatlaringizga nafaqat ko’proq odam kirishi mumkin, balki u yanada toza va tushunarli kod hosil bo’lishiga olib keladi. Siz sodda, aniqroq va oson bajarilishi mumkin bo’lgan narsalarni o’ylashga majbursiz.
Swagger asboblar paneli
Swagger yuragi bu uning o’ziga xos xususiyatidir. Swagger spetsifikatsiyasi — bu API amaliyotlarini (parametrlarni, yo’llarni, javoblarni, modellarni va boshqalarni qanday aniqlash mumkin) standartlashtiradigan qoidalar to’plami. Swaggerning har bir boshqa qismlari shu qoidalar asosida ishlaydigan API hujjatlarini o’zlashtirish yoki yaratishga xizmat qiladi.
Ushbu xususiyat bu arxitekturaning qoni bo’lsa-da, Swagger tashkil etilganidan beri foydalanuvchilar uchun ochiq kodli manba bo’lib xizmat qilib kelmoqda. Bu foydalanuvchilarga nafaqat butun ekotizimlarini ma’lum qoidalarga asosan optimallashtirish imkoniyatini balki o’z tizimlariga muvofiq ravishda yangi vositalar (SDK yaratish, dinamik hujjatlar va server integratsiyasi) ishlab chiqishga ham imkon yaratadi.
Swagger dasturini amalga oshirishga yordam beradigan bir nechta asosiy vositalar mavjud.
Swagger muharriri
Swagger muharriri ko’plab muammolarni hal qiladigan qulay vositadir. Siz hujjatlaringizni YAML yoki JSON ko’rinishida yozishingiz mumkin va uni avtomatik ravishda Swagger spetsifikatsiyasiga solishtirishi imkoniyatiga ega bo’lasiz. Muharrir orqali yo’l qo’yilgan xatolar aniqlanadi va ularga boshqa alternativalar taklif etiladi. Shu tarzda, hujjatlarni nashr etganda, uning xatosiz ekanligiga amin bo’lishingiz mumkin.
Foydalanuvchi interfeysi
Hujjatlarni ishlab chiqaruvchiga ko’p vaqt sarflashining sabablaridan biri shundaki, u juda tartibli bo’lib, navigatsiya qilinishi kerak. Siz qayerga misollar keltirishingiz, usullaringizni qanday tartibga solish va har bir qo’ng’iroq uchun qancha ma’lumot berish haqida tashvishlanishingiz kerak bo’ladi. Swagger faylingizni namoyish qilishning bitta varianti — Swagger-UI. Bu mavjud JSON yoki YAML hujjatni oladi va interfaol hujjatlarni yaratadi.
Siz quyidagi ko’rinishga ega xujjatga ega bo’lasiz.
Har bir usul (olish, qo’yish, joylashtirish, o’chirish) kengaytirilishi mumkin. «Operatsiyalarni kengaytirish» tugmachasini bosish orqali siz avtomatik ravishda yaratilgan misol yordamida parametrlarning to’liq tavsifini olasiz. Siz qo’ng’iroq qiymatlarini sinab ko’rishingiz va javob xabarini ko’rishingiz mumkin. Bu qulay, ammo afsuski, hali juda yaxshi foydalanuvchi tajribasi yo’q.
API landshaftini o’zgartirish
Git qanday qilib ishlab chiqaruvchilar uchun haqiqatan ham ochiq manbali platformaga aylangani singari, Swagger ham API dizayniga eng mashhur yondashuv sifatida paydo bo’ldi. Yaqinda u Linux Foundation-ga Open API Initiative nomi bilan ko’chirildi va Google, Microsoft, Intuit va Atlassian kabi kompaniyalar tomonidan qo’llab-quvvatlandi. Ushbu tashabbus «sotuvchiga neytral tavsif formatini yaratish, rivojlantirish va ilgari surishga qaratilgan.» API tavsiflashning umumiy tiliga ega bo’lish vositalarni ishlatishni ancha osonlashtiradi va bizning API tuzish va iste’mol qilish usulimizni samarali ravishda o’zgartiradi.
Manba:
API
Swagger nima va nima uchun bu muhim?