نحوه کار با Swagger به چه شکلی می باشد؟

1. دسترسی به رابط کاربری Swagger UI:

   • ز طریق یک آدرس URL اختصاصی (مانند [آدرس API]/swagger-ui/) به رابط کاربری Swagger UI دسترسی پیدا می‌کنید. این آدرس توسط پرشین ای پی آی در اختیار شما قرار می‌گیرد.
   • با باز کردن این URL در مرورگر خود، یک صفحه وب تعاملی را مشاهده خواهید کرد.

2. مشاهده نقاط پایانی (Endpoints):

   • در رابط کاربری Swagger UI، لیستی از نقاط پایانی API (URLهای مختلفی که API ارائه می‌دهد) بر اساس دسته‌بندی (مثلاً بر اساس منبع یا عملکرد) در کنار صفحه یا به صورت دسته‌های باز/بسته نمایش داده می‌شود.
   • با کلیک بر روی هر دسته یا نقطه پایانی، جزئیات مربوط به آن باز می‌شود.

3. بررسی جزئیات یک نقطه پایانی:

   • هنگامی که یک نقطه پایانی را باز می‌کنید، اطلاعات زیر را مشاهده خواهید کرد:
     • HTTP Method: (GET، POST، PUT، DELETE و غیره) نوع درخواست مورد نیاز برای تعامل با این نقطه پایانی.
     • URL Path: آدرس دقیق این نقطه پایانی.
     • Summary و Description: توضیح مختصری و شرح مفصل درباره عملکرد این نقطه پایانی.
     • Parameters: پارامترهای مورد نیاز برای ارسال درخواست. این شامل:
       • Path Parameters: پارامترهایی که در خود URL قرار می‌گیرند (مثلاً /users/{id}).
       • Query Parameters: پارامترهایی که بعد از علامت ? در URL می‌آیند (مثلاً /users?page=1).
       • Header Parameters: پارامترهایی که در بخش Header درخواست HTTP ارسال می‌شوند (مثلاً Authorization).
       • Request Body: برای متدهایی مانند POST و PUT، ساختار داده‌ای که باید در بدنه درخواست ارسال شود (معمولاً به فرمت JSON).
     • Responses: پاسخ‌های احتمالی که API می‌تواند برگرداند، همراه با کدهای وضعیت HTTP (مانند ۲۰۰ OK، ۴۰۰ Bad Request، ۵۰۰ Internal Server Error) و ساختار بدنه پاسخ (به فرمت JSON).
     • Security: مکانیزم‌های احراز هویت مورد نیاز برای دسترسی به این نقطه پایانی.

4. تلاش برای ارسال درخواست (Try it out):

   • رابط‌های کاربری Swagger UI دکمه‌ای با عنوان “Try it out“ یا مشابه آن را برای هر نقطه پایانی ارائه می‌دهند.
   • با کلیک بر روی این دکمه، فیلدهای ورودی برای پارامترهای مختلف فعال می‌شوند.

5. وارد کردن مقادیر پارامترها:

   • مقادیر مورد نظر خود را در فیلدهای مربوط به پارامترهای Path، Query و Header وارد کنید.
   • اگر نقطه پایانی نیاز به Request Body دارد، یک نمونه ساختار JSON در اختیار شما قرار می‌گیرد که می‌توانید آن را با داده‌های مورد نظر خود ویرایش کنید.

6. اجرای درخواست (Execute):

   • پس از وارد کردن تمام پارامترهای مورد نیاز، روی دکمه‌ “Execute“  کلیک کنید.
   • Swagger UI یک درخواست HTTP به API ارسال می‌کند.

7. مشاهده پاسخ:

   • پس از دریافت پاسخ از API، Swagger UI آن را در بخش “Responses“ نمایش می‌دهد. این شامل:
     • Code: کد وضعیت HTTP پاسخ.
     • Headers: هدرهای پاسخ HTTP.
     • Body: بدنه پاسخ (معمولاً به فرمت JSON).
     • Response Schema: ساختار داده‌ای که در بدنه پاسخ انتظار می‌رود.

8. بررسی مثال‌ها و اسکیماها:

   • Swagger UI مثال‌هایی از ساختار درخواست و پاسخ برای هر نقطه پایانی ارائه می‌دهد.
   • همچنین، شما می‌توانید اسکیما (Schema) یا ساختار داده‌ای مورد انتظار برای درخواست و پاسخ را مشاهده کنید تا نوع داده‌ها و فرمت آن‌ها را درک کنید.

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