68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
# راهنمای فارسی 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 فعلی استفاده کنید.
|