احسان رضایی

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 توسط شما باشه.