اگر توسعه دهنده backend باشید قطعا تا به حال براتون پیش اومده که خواستید api سرویسی که توسعه دادید رو به مدیر ارشد تیمتون و یا توسعه دهنده های frontend تحویل بدید. هرکدوممون از یه راهی استفاده کردیم، یا شفاهی براشون توضیح دادیم و یا توی تلگرام آدرس و اطلاعات api رو براشون فرستادیم و یا نهایت از Postman استفاده می کنیم ولی خب مشکلی که داره اینه که نمیشه محیط‌های ایجاد شده رو در حالت رایگان با بقیه توسعه دهنده ها به اشتراک گذاشت و به محض کوچکترین تغییر باید همه دوباره ایمپورتش کنند.
اما خوشبختانه دوست عزیزمون، شرکت SmartBear به کمکمون اومده و swagger رو برامون توسعه داده.
یک ابزار open-source برای توضیح، مستندسازی و تست سرویس های REST API است که کتابخانه های آن برای اکثر زبان ها و فریمورک های رایج توسعه وب موجود می باشد. از طریق اون میتونید انواع اطلاعات مربوط به سرویس های توسعه داده شده، از جمله ورودی ها و خروجی ها و انواع هرکدوم رو مستند کنید و همچنین میشه توی همون محیط اون ها را تست کرد.
چند وقت پیش بود که برای پروژه ای که به تازگی گرفته بودم، برای مستند سازی apiهای سیستم، تصمیم گرفتم که از swagger استفاده کنم. با swagger از قبل و توی پروژه ای که حدود 6ماه قبل مشغولش بودم آشنا بودم اما خودم از صفر اجراش نکرده بودم و قبل از ورود من به پروژه، برنامه نویس ارشد تیم روی پروژه سوارش کرده بود و من صرفا مستنداتم رو بهش اضافه میکردم.
اما حالا بنا بود که خودم از صفر اجراش کنم. اما نکته ای که توجهم رو جلب کرد این بود منبع فارسی برای آموزش swagger بسیار کم بود و برای laravel که اصلا نبود! پس تصمیم گرفتم که یک توضیح مختصر فارسی برای پیاده سازی swagger در laravel آمده کنم.
دست به کار شدم و در اولین حرکت طبق عادت همیشگی خیلی هامون گوگل کردم “swagger Laravel” و به یک ریپوزیتوری github یک کتابخونه برخوردم که swagger رو روی laravel پیاده سازی کرده بود.
این نکته رو اضافه کنم که توی این مقاله از لاراول 5.8 استفاده میکنم و قراره کتابخونه DarkaOnLine/L5-Swagger رو معرفی کنم و ازش استفاده کنم.
این کتابخانه نسخه های مختلفی داره که با مراجعه به ریپوزیتوری github میتونید با توجه به نسخه لاراولی که دارید استفاده میکنید نسخه مناسبتون رو انتخاب کنید
اما من چون از laravel 5.8 استفاده میکردم ورژن 5.8 این کتابخونه رو نصب کردم:
composer require "darkaonline/l5-swagger:5.8.*"
اگر از نسخه های >= 5.5 لاراول استفاده میکنید نیازی به افزودن L5SwaggerServiceProvider به تنظیمات لاراول نیست اما اگر اینطوری نیست فایل AppServiceProvider را در مسیرconfig/app.php باز کنید و این خط رو به بخش providersاضافه کنید:
L5Swagger\L5SwaggerServiceProvider::class,
سپس دستور زیر رو اجرا کنید تا فایل های تنظیمات و view صفحه swagger برای شما ایجاد شود:
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
بعد از اجرای این دستور فایل های زیر ایجاد خواهند شد:
Copied File [\vendor\darkaonline\l5-swagger\config\l5-swagger.php] To [\config\l5-swagger.php] Copied Directory [\vendor\darkaonline\l5-swagger\resources\views] To [\resources\views\vendor\l5-swagger] Publishing complete.
برای ایجاد مستندات، swagger یک مجموعه annotation برای مشخص کردن و دستکاری ورودی ها و خروجی ها پیشنهاد داده است که می توان آنها را به controller و یا modelها اضافه کرد و یا آنها را در یک فایل جداگانه قرار داد که می توانید نمونه هایی از آن را در اینجا، اینجا و اینجا مشاهده بفرمایید (آموزش annotation ها را در بخش های بعدی به طور جداگانه توضیح خواهم داد).
حالا اگر annotation ها رو درست و کامل نوشته باشید با دستور زیر میتونید مستندات خودتون رو ایجاد کنید:
php artisan l5-swagger:generate
و یا در فایل env. میتونید مقدار L5_SWAGGER_GENERATE_ALWAYS را برابر true قرار بدید تا مستنداتتون به طور خودکار ایجاد بشن.
حالا میتونید از طریق yourdomain.com/api/documentation به مستندات خود دسترسی داشته باشید.
به قول یک دوستی که میگفت:
کاش کد نویسایی که داکیومنت نمی نویسن برن زیر تریلی!
پس خواهشا داکیومنت بنویسید :)
