تدوین: مهندس محبوبه مهدی زاده
تاريخ آخرين ويرايش: 18 خرداد 1399
اداره سامانه های کاربردی – مرکز فاوای دانشگاه فردوسی مشهد
Swagger چیست؟
APIها امروزه دنیای مدرن وب را تحت تاثیر خود قرار داده‌اند. در واقع APIها با نمایان ساختن بخشی از عملکرد و اطلاعات نهفته موجود در برنامه‌ها، تعامل آنها با محیط خارج را ممکن می‌کنند.
هراندازه یک داکیومنت مربوط به API قوی باشد به همان اندازه آن API نیز خوب خواهد بود. یک APIخوب زمانی که مردم نحوه استفاده از آن را ندانند؛ میتواند به ابزاری بلا استفاده و غیرمفید تبدیل شود و اینجاست که مشخص میشود چرا مستندسازی میتواند برای یک API تجازی ضروری باشد. اما ایجاد و حفظ یک داکیومنت خوب که درک آن آسان، تعامل با آن لذت‌بخش ونیز مورد رضایت مصرف‌کننده باشد؛ میتواند به‌شدت چالش‌برانگیز باشد. با اینکه ایجادمستندات عالی نیاز به صبر و تلاش دارد، اما این امر دلالت مستقیم بر ماندگاری و مقبولیت API دارد. با انتخاب ابزار مستندسازی مناسب، می‌توانیم داکیومنت‌های قابل‌فهم‌تری ایجاد کنیم.
Swagger یک الگوی توصیفی برای تولید و داکیومنت کردن Web APIهاست که بعدها به یک استاندارد، به نام OpenAPI Specification تبدیل شد.
به زبان ساده، یک استاندارد برای تعریف API نوشته شده است و Swagger ابزارهای لازم برای این کار را در اختیار قرار میدهد، درواقع شما بوسیله‌ی یک ساختار JSON یا YAML معین می کنید که APIهای شما چه روت (Route) هایی دارد، چه ورودی هایی دریافت می کند و خروجی چه مسیری خواهد بود.
علاوه بر این وقتی یک استاندارد تعیین میشود، ابزارهای بسیاری تولید می‌شوند که زبان یکدیگر را درک می‌کنند. تعدادی از این ابزارها عبارتنداز:
Swagger Editor:
اولین ادیتور اپن‌سورسِ کاملا اختصاصی برای APIهای مبتنی بر OpenAPI می‌باشد. این ابزار یک محیط در اختیار کاربر قرار می‌هد که در آن میتواند مسیرهای موجود در API را تعیین کند، توضیحات آن را بنویسد و مشخص کند که چه پارامترهایی باید برای آن ارسال شود و خروجی آن چه خواهد بود. شما می‌توانید API خود را در این ادیتور طراحی، توصیف و مستندسازی کنید.
Swagger UI :
این ابزار یک فایل معتبر Swagger را دریافت میکند و توضیحات آن را نمایش میدهد و امکان تست نیز وجود دراد. در واقع این ابزار، مستندات API را نمایش و تست آن را انجام میدهد.
Swagger CodeGen :
یک تولیدکننده کد(code generator) اپن سورس است که شامل مجموعه ابزارهایی است که این امکان را به کاربر میدهد که از یک فایل Swagger (تعریف شده با RESTful API) کدهای سمت سرور (server stubs) و یا سمت کلاینت (client SDK) را تولید کند.
Swagger فقط یک الگوی توصیفی برای نوشتن API هست و کدی نوشته نمی‌شود، فقط تعریف می کنید که API به چه شکلی خواهد بود. اصولاً این موضوع با برنامه نویسی Backend ارتباط پیدا می کند و ارتباط مستقیمی با زبان‌هایی مثل اندروید ندارد.
محصولاتی که تحت وب هستند، همیشه یک بخش سرور و یک بخش کلاینت دارند. کلاینت ها با سرور ارتباط برقرار می کنند، که این کلاینت ها میتوانند وبسایت یا اپ موبایل یا دسکتاپ و یا همه‌ی اینا باشند.
ضرورت وجود ابزارهایی مثل Swagger زمانی بیشتر نمایان میشود که ایجاد API و کلاینت آن را به صورت موازی انجام دهیم. با داشتن یک فایل swagger میتوان در Swagger UI کل مسیرهای API را به همراه توضیحات و نحوه‌ی استفاده از آن را مشاهده نمود، و نیز API را تست کرد، یعنی بدون نوشتن کد، میتوان API را کاملاً تست کرد و در صورت تمایل با استفاده از ابزار CodeGen تمامی فایل‌های آماده برای استفاده در اندروید یا جاوا اسکریپت و... را ایجاد کرد. و این موضع بسیار کار تیمی را بهبود می‌بخشد.
نظارت و مدیریت API های مختلف نیازمند کار زیادی می باشد .از دیگر مزایای استفاده از ابزارهای swagger در هنگام کار با Web API ها میتوان به موارد زیر اشاره نمود:
تست و debug کردن API ها نیاز به عیب یابی دارد: انجام این کار برای برنامه های موبایل خیلی سخت و طاقت فرسا است . IDE ها (محیطهای توسعه یکپارچه ) هم برای راحت تر کردن این قضیه وجود دارد ولی به مناسب Debugg کردن API ها نمی‌باشد.
تعیین منبع مشکلات از طریق عملکرد کاربر در همان لحظه: برنامه نویسان دوست دارند استفاده API ها را در یک برنامه مشاهده کنند. مثلا زمانی که کاربر در هنگام استفاده از یک برنامه با خطایی مواجه می شود، برنامه نویس دوست دارد بداند چه تقاضایی باعث بوجود آمدن چنین خطایی شده و به چه دلیل .
تولید پاسخهای سفارشی از WebAPI : علی‌الخصوص زمانی که برنامه و API در یک خط موازی حرکت می‌کنند یا زمانی که یک ویژگی خاص جدید نیازمند بروزرسانی API می ماند تا قابل استفاده شود.
میتوان اینطور نتیجه گرفت که:
«برای تسریع استفاده از API های تحت وب برنامه نویسان نیازمند نمونه های استفاده از آن API ها، مستندات منسجم و با مفهوم و هر آن چیزی هستند که در صرفه جویی وقتشان کمکشان کند. برای همین نیازمندی، ساختارهایی همانند Swagger موجود است که ثابت کرده بسیار کارامد هستند.»
Swagger Editor
Swagger Editor یک ادیتور open source برای طراحی، تعریف و مستندسازی APIهای RESTful در swagger specification می باشد. سواگر ادیتور به صورت رایگان و آنلاین در editor.swagger.io قابل دسترس می‌باشد. سورس کد آن نیز در gethub موجود است:
GitHub: https://github.com/swagger-api/swagger-editor
این ادیتور در هر مرورگری کار میکند. در مرورگر اجرا میشود و به طور کامل client-side javascript ساخته میشود و نگرانی بابت ذخیره اطلاعات API در سرورهای سواگر نمی‌باشد. در این ادیتور ذخیره‌سازی ابری وجود ندارد، بنابراین در صورت نیاز باید اطلاعات را به صورت لوکال ذخیره کرد. از سواگر ادیتور می توان به صورت لوکال یا از نسخه تحت وب آن استفاده نمود.
پیش نیازها برای نصب لوکال Swagger Editor
موارد زیر قبل از دانلود و اجرای Swagger Editor باید بر روی سیستم نصب شود:
Nodejs
هنگامی که nodejs با موفقیت نصب شد، بایستی npm نیز به صورت کامل نصب شود که میتوان با استفاده از دستور زیر در محیط CMD این کار را انجام داد:
npm install;
اگر سیستم عامل ویندوز است:
میتوان از nodejs.msi برای نصب nodejs استفاده کرد. فایل installer یا همان msi سه عمل را انجام میدهد. ابتدا برنامه nodejs را داخل یک پوشه کپی می کند(مسیر انتخابی). در گام دوم npm را نصب میکند. و در آخر، آدرس nodejs را در متغیر محیطی PATH قرار می دهد تا بتوان از node در command prompt استفاده کرد(اگر بعد از نصب سیستم reboot شود بهتر است).
در صورت استفاده از فایل exe باید آن را در پوشه ای ذخیره کرد و بعد از آن، آدرس node را در path ایجاد و در نهایت npm را به صورت دستی نصب نمود( در اینجا باید فایل zip مربوط به npm را در پوشه ای که nodejs قرار دارد extract کنیم)
Git
برای clone کردن اطلاعات بایستی git بر روی سیستم نصب شود.
پس از نصب موارد بالا برای clone کردن سواگر، در محیط cmd وارد مسیر hdocs در Xampp یا (www در wamp) می‌شویم و دستور زیر را اجرا می‌کنیم:
> git clone https://github.com/swagger-api/swagger-editor.git swagger-editor-doc
با این دستور swagger-editor در مسیر موردنظر قرار می‌گیرد. حال میتوان swagger-editor-doc را اجرا کرد.
زمانی که ادیتور را برای اولین بار اجرا می‌کنیم، در این محیط Swagger Petstore API نمایش داده میشود (یک API ساده است که توسط پروژه‌های سواگر برای نمایش قابلیت‌های گسترده OpenAPI specification بکار می‌رود و در سواگر ادیتور به عنوان مثال پیش‌فرض می‌باشد).
همانطور که می‌بینید، swagger editor یک محیط دو قسمتی را نشان میدهد:
سمت چپ شامل مشخصات (specification) در قالب YAML است و سمت راست مستندات API تعاملی تولیدشده را نشان میدهد. هرگونه ویرایش در سمت چپ ادیتور، بر روی اطلاعات سمت راست راست تاثیرگذار است و تغییرات در همان لحظه در سمت راست نمایان میشود.
تعاریف OpenAPI را میتوان بصورت YAML یا Json مرتب کرد. با اینکه swagger editor هر دو مورد را قبول میکند ولی استفاده از YAML را در اولویت قرار میدهد و زمانی‌که شما فایل Json را کپی یا Paste می‌کنید از شما درخواست میکند تا آن را تبدیل کنید (convert).
یک نوار منو در قسمت بالایی ادیتور وجود دارد که شامل منوهای زیر می‌باشد:
File:
با استفاده از این منو میتوان فایل OpenAPI را import کرد. این فایل میتواند از فایل‌هایی باشد که بر روی سیستم شما ذخیره است (منو Import File) و یا اینکه میتواند یک URL باشد (Import URL). با استفاده از زیرمنوهای Save as YAML و Convert and save as json میتوان ورژن‌های YAML یا JSON مواردی که در ادیتور تعریف شده است را دانلود کرد. زیرمنو Clear editor صفحه ادیتور را پاک میکند.
Edit
در این منو تنها یک زیرمنو (Convert to YAML) وجود دارد که با استفاده از آن میتوان json را به YAML تبدیل کرد.
Generate Server و Generate Client:
این دو منو، لیستی از انواع مختلف زبان‌های برنامه‌نویسی و فریمورک‌ها را نمایش می‌دهند. اگر بر روی یکی از آنها کلیک کنید، یک فایل zip دانلود میشود که شامل بدنه و طرح پروژه برای تولید یا تحلیل API با تعاریف شما است.
این دو ویژگی (Generate Server و Generate Client) در پروژه open source Swagger Codegen ساخته میشود. این بدین معناست که برخلاف مابقی قسمت‌های اپلیکیشن، اگر شما از این دو ویژگی استفاده کنید، تعریف OpenAPI برای پردازش به سرور فرستاده میشود و ر روی کلاینت پردازش نمی‌شود.
لازم به ذکر است که ادیتور swagger ابزاری برای کمک در یادگیری نوشتن OpenAPI است و مستقیما با تعاریف API قابل خواندن برای ماشین (machine-readable) کار میکند. این ادیتور، ویژگی‌های استاندارد IDE مثل هایت‌لایت کردن سینتکس، auto complete و اعتبارسنجی (validate) را دارد، اما یک طراح API بصری (visual API designer) نیست و به طور کلی جامعه هدف این ادیتور تنها برنامه‌نویسان می‌باشند و برای افراد غیر برنامه‌نویس مناسب نیست.
ایجاد یک openAPI definition:
برای ایجاد تعریفی از openApi در ادیتور swaager ابتدا باید محیط ادیتور را پاک کنیم(File → Clear editor).
ساختار پایه:
اولین موردی که باید در محیط ادیتور نوشته شود، دستوری است که باید نوع و ورژن specification را مشخص کند.
Swagger: ‘2.0’
آبجکت‌ها:
|
نام |
اجباری |
توضیحات |
|
swagger |
✓ |
از نوع رشته. نوع و ورژن specification |
|
info |
✓ |
یک متادیتا درمورد API. |
|
servers |
✓ |
یک آرایه از آبجکت‌های سرورکه اطلاعات ارتباطی با یک سرور هدف را ارائه میدهد. اگر server تعریف نشده باشد یا یک آرایه خالی باشد؛ مقدارپیش‌فرض یک آبجکت server با مقدار url ای برابر ./ خواهد بود |
|
paths |
✓ |
عملیات‌های و مسیرهای دردسترس برای API |
|
components |
یک المنت برای نگهداری طرح‌های(schemaها) متنوع برای specification |
|
|
security |
یک اعلان از مکانیزم‌های امنیتی که میتوانند در سراسر API استفاده شوند. لیست مقادیر شامل اشیاء موردنیاز امنیتی جایگزین است که میتواند استفاده شود. فقط یک مورد از آبجکت‌های الزامی امنیتی نیاز است تا اجازه درخواست تایید شود. عملیات‌های فردی (individual operation) میتواند این تعریف را تغییر دهد(override). |
|
|
tags |
لیستی از تگ‌های استفاده شده توسط specification با متادیتا اضافی. ترتیب تگ‌ها میتواند منعکس‌کننده ترتیب آنها بوسیله ابزارهای پارسینگ باشد |
|
|
externaldoc |
داکیومنت خارجی |
آبجکت Info:
عموما بهتر است که اطلاعاتی کلی در مورد API در داخل مشخصات گنجانده شود؛ اگر قرار است API به صورت عمومی در دسترس قرار گیرد، از این طریق میتوان اعتماد کاربر به محصولات کمپانی را افزایش داد . برای اختصاص API metadata، از خصیصه‌های آبجکت Info استفاده می‌کنیم. با استفاده از info می‌توانیم اطلاعات قابل فهم برای کاربر مثل عنوان، توضیحات، اطلاعات تماس و ... را تنظیم کنیم.
خصیصه‌های (property) آبجکت info عبارتند از:
|
نام |
نوع |
اجباری |
توضیحات |
|
title |
string |
✓ |
عنوان اپلیکیشن |
|
Version |
string |
✓ |
ورژن(نسخه) API. برای مقداردهی میتوان از ورژن معنایی مثل 1.0.0 استفاده کرد یا رشته دلخواهی مثل 0.99-beta بکار برد |
|
description |
string |
توضیحات API. متنی دلخواه در قالب html یا markdown |
|
|
termsOfService |
string |
لینک به صفحه‌ای که شرایط خدمات توضیح داده شده است. مقدار این فیلد باید به فرمت URL باشد |
|
|
contact |
Contact object |
اطلاعات تماس که شامل خصیصه‌های name، email و url می‌باشد. name: نام یا اطلاعات متنی. اگر از این خصیصه به تنهایی کاربردی نداردشود. اگر email یا url مقداردهی شده باشند در لینکی که با آدرس email یا url ایجاد میکند از مقدار name به عنوان hypertext لینک استفاده میشود و اگر name مقداردهی نشده باشد از مقدار پیش‌فرض آن یعنی the developer استفاده میشود Email: مقداری با فرمت پست الکترونیک دریافت میکند. این فیلد به صورت لینک است که با کلیک بر روی آن امکان ارسال نامه به ایمیل ثبت شده وجود دارد url : آدرس url که لینک آن در خروجی نمایش داده می شود. |
|
|
license |
License object |
شامل خصیصه‌های license و url می‌باشد. name: نام license که در صورت استفاده از url به عنوان hypertext لینک به کار می‌رود. url: آدرس url مربوط به شرح license |
|
|
externalDocs |
لینکی به یک داکیومنت خارجی(در صورت وجود) که شامل خصیصه‌های description و url است. Code یا ابزارهای تولید مستندات میتواند description را به عنوان متن لینک استفاده کند. description: توضیح url: آدرس |
آبجکت server :
یک شیء که یک سرور را نشان می دهد.
فیلد‌های ثابت(propertyها)
|
نام |
نوع |
اجباری |
توضیحات |
|
url |
String |
✓ |
یک url به هاست مقصد. این url از متغیرهای سرور پشتیبانی میکند و میتواند نشبی باشدکه نشان میدهد محل هاست با محلی که داکیومنت OpenAPI ذخیره شده است، مرتبط می‌باشد. جایگزینی متغیر زمانی ایجاد میشود که یک متغیر در براکت {} نامگذاری شود. |
|
description |
String |
یک رشته اختیاری برای توصیف هاست طراحی شده با Url. برای نمایش متن از CommonMarl استفاده میشود. |
|
|
variables |
Map(string، شیserver variable) |
یک نگاشت بین نام متغیر و مقدار آن. مقدار برای جایگزینی در قالب url سرور استفاده میشود. |
Swagger ui:
Swagger ui پارامترهای پیکربندی (configuration) را به چهار روش میتواند دریافت کند:
با استفاده از swagger-config.yaml در دایرکتوری ریشه پروژه
آبجکت پیکربندی به صورت یک آرگومان به Swagger ui ارسال میشود (SwaggerUI({.. }))
داکیومنت پیکربندی از یک configUrl خاص واکشی(fetch) میشود.
آیتم‌های تنظیمات به صورت جفت های کلید/مقدار (key/value) در رشته پرس‌وجو url ارسال میشود.
parameters
پارامترهایی با dot هایی در نام آنها، رشته هایی تک هستند که برای تنظیم پارامترهای زیرمجموعه بکار می‌روند و نشانگر یک ساختار تودرتو نیستند.
برای خوانایی بیشتر، پارمترها بوسیله دسته((category گروهبندی و براساس حروف الفبا مرتب می‌شوند.
نشانه‌گذاری type ها فرمتی مانند زیر دارد:
String = “” : به معنی نوع رشته با مقدار پیش‌فرض “” می‌باشد
String=["a"*, "b", "c", "d"] به این معنی است که نوع رشته میتواند مقادیر a،b،c یا d داشته باشد. علامت * مشخص میکند که a مقدار پیش‌فرض است.
Core
|
نام پارامتر |
متغیر Docker |
نوع |
توضیحات |
|
configUrl |
CONFIG_URL |
String |
url برای واکشی (fetch) داکیومنت پیکربندی خارجی |
|
dom_id |
DOM_ID |
string |
اگر domNode مقداردهی نشده، این پارمترالزامیست. شناسه یک عنصر dom که در آن swaggerUi رابط کاربری را برای swaager قرار می دهد. |
|
domNode |
--- |
element |
اگر dom_id مقداردهی نشده، این پارمتر الزامیست. عنصر html dom است که در داخل آن swaggerUi رابط کاربری را برای swaager قرار می دهد. dom_id را overrids میکند |
|
spec |
spec |
Object={} |
یک شی js برای توصیف openAPI Specification. زمانی که از این پارامتر استفاده شود ، پارامتر url بررسی (parse) نمی‌شود. این امر برای تست specificationهایی که بصورت دستی بدون میزبانی (hosting) آنها بدست آمده؛ مفید است |
|
url |
URL |
String |
url که به تعریف API اشاره میکند (عموما swagger.json یا swagger.yml). اگر urls یا spec استقاده شود؛ این پارامتر نادیده گرفته میشود. |
|
urls |
URLS |
Array |
یک آرایه از اشیای تعریف API ([{url: "<url1>", name: "<name1>"},{url: "<url2>", name: "<name2>"}]) . بوسیله پلاگین Topbar استفاده میشود. وقتی این پارمتر استفاده میشود و پلاگین Topbar فعال است، پارامتر url پارس نمی‌شود.Name ها و URL ها باید در تمامی آیتم‌ها در این آرایه یکتا باشند ، به دلیل اینکه به عنوان شناسه‌ها(identifiers) استفاده می‌شوند. |
|
urls.primaryName |
URLS_PRIMARY_NAME |
String |
در مواقعی که از urls استفاده میشود، میتوان از این ساب پارامتر استفاده کرد. اگر این پارمتر باname یکی از مشخصه‌های (spec) ارائه شده در urls منطبق باشد، آن مشخصه در زمان لود Swagger-UI نمایش داده میشود.(به طور معمول درحالت پیش‌فرض اولین مشخصه در urls در زمان لود Swagger-UI نمایش می‌یابد) |