احسان رضایی

یک توسعه دهنده

مستند سازی خودکار و ایجاد یک محیط تعاملی برای Web API با استفاده از swagger

در PHP , / تاریخ ارسال 19-03-1396 / 3 نظر / آخرین ویرایش 01-01-1403

swagger اجازه میده یک ساختار توصیفی از API خودتون بسازید. چرا مفید، عالی و کاربردی به نظر میرسه؟ چون میتونیم به طور خودکار برای API خودمون مستندات زیبا و یک محیط تعاملی ایجاد کنیم، همچنین امکان تست API رو هم برامون فراهم میکنه. swagger این کارُ با خواندن به اصطلاح حاشیه ها/یادداشت ها یا کامنت های داخل سورس انجام میده.

/**
 * @SWG\Get(
 *   path="/customer/{customerId}/rate",
 *   summary="List customer rates",
 *   operationId="getCustomerRates",
 *   @SWG\Parameter(
 *     name="customerId",
 *     in="path",
 *     description="Target customer.",
 *     required=true,
 *     type="integer"
 *   ),
 *   @SWG\Parameter(
 *     name="filter",
 *     in="query",
 *     description="Filter results based on query string value.",
 *     required=false,
 *     enum={"active", "expired", "scheduled"},
 *     type="string"
 *   ),
 *   @SWG\Response(response=200, description="successful operation"),
 *   @SWG\Response(response=406, description="not acceptable"),
 *   @SWG\Response(response=500, description="internal server error")
 * )
 *
 */

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

swagger

 

پیشنهاد

کتاب‌ها

کتاب الگوهای طراحی به بیان ساده(design patterns / دیزاین پترن)

در مهندسی نرم افزار، design patterns(الگوهای طراحی) راه حل‌های قابل استفاده برای مشکلاتی هستند که معمولاً در طراحی نرم‌افزار اتفاق می افتند.

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

کتاب refactoring / ریفکتورینگ

Refactoring مجموعه‌ای از تکنیک‌هاست که به منظور اصلاح و بهبود کدهای قبلی بدون تغییر در عملکرد و رفتارشان جهت خوانایی، کارامدی و قابلیت نگهداری بیشتر انجام می‌شود.

در کتاب Refactoring اثر Martin Fowler نوشته شده: refactoring تکنیک مرتب/منظم سازی برای تجدید ساختار کد موجود است. تغییر ساختار داخلی کد بدون تغییر رفتار خارجی آن.

refactoring یک سرمایه‌گذاری و راه حلی برای مقابله با کد کثیف و بدهی فنی است که باعث کاهش هزینه‌های توسعه نرم‌افزار در آینده خواهد شد.

ارسال نظر

یوشا در تاریخ 1396/03/25 - 10:26 نوشته
اینارو از کجا پیدا می کنی o:
پاسخ احسان:

کافیه مثل من تنبل باشی :D به دنبال هر چیزی میگردی تا کارتُ آسونتر و سریعتر کنی :P

sama در تاریخ 1397/04/05 - 12:09 نوشته
میشه نحوه تهیه مستندات ورژن WebApi با استفاده از swagger بگید؟
پاسخ احسان:

سلام. اگر فرصتی پیش بیاد حتما در موردش بیشتر مینویسم :)

elha در تاریخ 1399/04/20 - 13:17 نوشته
سلام . میشه لطفا نحوه تهیه مستندات رو با Swagger آموزش بدید؟ ممنون