football-next/SWAGGER-FA.md

راهنمای فارسی Swagger پروژه

این پروژه حالا یک مستندات Swagger/OpenAPI داخلی دارد که از APIهای فعلی کد تولید شده است.

مسیرها

• رابط Swagger UI: /swagger
• خروجی خام OpenAPI JSON: /api/openapi

کاربرد هر مسیر

• /swagger برای مشاهده، جستجو و تست Endpointها در مرورگر است.
• /api/openapi برای اتصال ابزارهای دیگر مثل Postman Import، Redoc، یا CI/CD مناسب است.

نحوه استفاده

1. پروژه را اجرا کنید.
2. در مرورگر به /swagger بروید.
3. از روی Tagها Endpoint مورد نظر را باز کنید.
4. در صورت نیاز روی Try it out بزنید و ورودی را پر کنید.
5. برای Endpointهای نیازمند احراز هویت، بهتر است ابتدا در همان مرورگر داخل برنامه لاگین کرده باشید.

احراز هویت

این پروژه از NextAuth با Session Cookie استفاده می‌کند.

• بیشتر APIهای کاربری با Session کار می‌کنند.
• APIهای ادمین علاوه بر Session، نقش ADMIN هم می‌خواهند.
• در Swagger نیازی به Bearer Token نیست، چون درخواست‌ها روی همان Origin اجرا می‌شوند و Cookie مرورگر قابل استفاده است.

دسته‌بندی Endpointها

• Auth: ثبت‌نام، Session و مسیرهای پایه NextAuth
• User: پروفایل و تست Session
• Team: ساخت و مدیریت تیم فانتزی
• Players: دریافت و مدیریت بازیکنان
• Countries: دریافت و مدیریت کشورها
• Matches: بازی‌ها، آمار، رویدادها و محاسبه امتیاز
• Rounds و Gameweeks: مدیریت بازه‌های مسابقات
• Quiz: کوئیز روزانه، نتایج و قرعه‌کشی
• Golden Cards: کارت‌های طلایی
• Payment: ساخت و تایید پرداخت
• Upload: آپلود عکس بازیکن

نکات مهم

• مسیر /api/payment/verify پاسخ JSON نمی‌دهد و کاربر را Redirect می‌کند.
• مسیر /api/upload/player-image از multipart/form-data استفاده می‌کند.
• برخی مسیرها مثل POST /api/admin/matches/{id}/calc-points از داده‌های ثبت‌شده قبلی استفاده می‌کنند و بدنه ورودی ندارند.
• مستندات بر اساس Routeهای فعلی پروژه نوشته شده؛ اگر API جدید اضافه شود باید lib/openapi.ts هم به‌روزرسانی شود.

نگهداری مستندات

فایل اصلی مستندات:

• lib/openapi.ts

Routeهای خروجی:

• app/api/openapi/route.ts
• app/swagger/route.ts

اگر API جدیدی اضافه کردید:

1. مسیر جدید را در paths اضافه کنید.
2. در صورت نیاز Schema مشترک را در components.schemas تعریف کنید.
3. اگر Endpoint نیازمند Session است، از Security فعلی استفاده کنید.