وظیفه سایت swagger [بایگانی]

Nevercom

جمعه 24 شهریور 1396, 06:43 صبح

Swagger یک الگوی توصیفی برای تولید Web API و داکیومنت کردن اون هست که بعدها تبدیل شد به یک استاندارد، به نام OpenAPI Specification

به زبان ساده، یک استاندارد برای تعریف API نوشته شده و Swagger ابزارهای لازم برای این کار رو در اختیار قرار میده، درواقع شما بوسیله‌ی یه ساختار JSON یا YAML معین می کنید که APIهای من این روت (Route) ها رو داره، این ورودی ها رو دریافت می کنه و این خروجی این مسیر خواهد بود.

علاوه بر این وقتی یک استاندارد تعیین میشه، کلی ابزار میشه تولید بشن که زبان همدیگه رو بفهمن. اول چندتا از این ابزارها رو توضیح میدم و بعد دقیق تر میگم که ارزش Swagger به چی هست:

Swagger Editor: این ابزار یک محیط در اختیارتون قرار میده که اونجا مسیرهای موجود در API رو تعیین کنید، توضیحاتش رو بنویسید و مشخص کنید که چه پارامترهایی باید براش ارسال بشه و خرجی اون چه خواهد بود.
Swagger UI: این ابزار یک فایل معتبر Swagger رو دریافت می کنه و توضیحات اون رو نشون میده و امکان تست رو میده. در واقع این میشه ابزار نمایش مستندات API و تست اون.
Swagger CodeGen: مجموعه ابزارهایی که امکان این رو به شما میده که از یک فایل Swagger کدهای سمت سرور و یا سمت کلاینت رو تولید کنید، مثلاً یه فایل Swagger رو که دریافت کردید میتونید با استفاده از این ابزار کدهای اندروید رو تولید کنه که راحت با این API ارتباط برقرار کنید

همونطور که گفتم Swagger فقط یک الگوی توصیفی برای نوشتن API هست و کدی این وسط نوشته نمیشه، فقط تعریف می کنید که API من این شکلی خواهد بود. اصولاً این موضوع با برنامه نویسی Backend ارتباط پیدا می کنه و ارتباط مستقیمی با اندروید نداره.

بعنوان یک برنامه نویس بک‌اند ارزش واقعی ابزار رو بخصوص در کار تیمی، از روی تجربه خدمتتون عرض می کنم. محصولاتی که تحت وب هستن، همیشه یک بخش سرور دارن و کلاینت ها که با این سرور ارتباط برقرار می کنن، حالا این کلاینت ها میتونن وبسایت یا اپ موبایل یا دسکتاپ و یا همه‌ی اینا باشن. در تیم ما که اندروید در محوریت قرار داره، همیشه یه کلاینت اندروید هست و یکی هم کلاینت وب که پنل مدیریتی کل این محصول هست.
قبلتر ها API رو که می نوشتم، بخش به بخش که تکمیل میشد به همکارام توضیح میدادم و بر اساس توضیحات من از API استفاده می کردن. اما اگر زمانی من نبودم هیچ راهی نبود که از APIها مطلع بشن، ضمن اینکه نوشتن داکیومنت همراه با توسعه‌ی API کار وقتگیری هست و این طور هم نیست که ابتدا کل API نوشته بشه و داکیومنتش آماده بشه و بعدن کلاینت ها ساخته بشه، درواقع برای سرعت بخشیدن به کار همه ی اینها بصورت موازی انجام میشن.

وقتی که با Swagger آشنا شدم و ازش استفاده کردم، شرایط به کل تغییر کرد، حالا فقط با داشتن یه فایل میشد تو Swagger UI کل مسیرهای API من رو با تمام توضیحاتش و نحوه‌ی استفاده دید، و همون لحظه اون API رو تست هم کرد، یعنی قبل اینکه یه خط کد بنویسن میتونن API من رو کاملاً تست کنن و باهاش آشنا بشن و پیاده سازیش کنن، حتی اگر مایل باشن میتونن با CodeGen همه ی فایل های آماده برای استفاده مثلاً در اندروید یا جاوا اسکریپت رو تحویل بگیرن.
از این بعد، به شدت کار تیمی رو بهبود می‌بخشه و بنظرم هر برنامه‌نویس بک‌اند باید از Swagger استفاده کنه (مگر اینکه جایگزین بهتری سراغ داشته باشه)

البته الگویی که من ازش استفاده می کنم کمی متفاوت هست، اما نتیجه یکسان هست، تیم من میتونن API من رو براحتی تست کنن و درک کنن، بدون اینکه نیاز باشه شخصاً تک تک مسیرها رو براشون شرح بدم.

خیلی وقت بود قصد کرده بودم مطلبی در مورد Swagger بنویسم که فرصتش پیش نیومد، پست شما مقدمه ای شد بر این، و شاید به زودی مطلبی آموزشی در موردش تهیه کنم.