SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1d71b588cbce64c1d9377939ff65bb96a3273d2a
sam-api/app/Swagger/v1/PlanApi.php
hskwon 45780ea351 feat: 구독/결제 API 확장 (Plan, Subscription, Payment) 
- Plan/Subscription/Payment 모델에 상태 상수, 스코프, 헬퍼 메서드 추가
- PlanService, SubscriptionService, PaymentService 생성
- PlanController, SubscriptionController, PaymentController 생성
- FormRequest 9개 생성 (Plan 3개, Subscription 3개, Payment 3개)
- Swagger 문서 3개 생성 (PlanApi, SubscriptionApi, PaymentApi)
- API 라우트 22개 등록 (Plan 7개, Subscription 8개, Payment 7개)
- Pint 코드 스타일 정리
2025-12-18 16:20:29 +09:00

304 lines
14 KiB
PHP
Raw Blame History

<?php
namespace App\Swagger\v1;
/**
* @OA\Tag(name="Plans", description="요금제 관리")
*
* @OA\Schema(
* schema="Plan",
* type="object",
* description="요금제 정보",
*
* @OA\Property(property="id", type="integer", example=1, description="요금제 ID"),
* @OA\Property(property="name", type="string", example="스타터", description="요금제명"),
* @OA\Property(property="code", type="string", example="starter", description="요금제 코드"),
* @OA\Property(property="description", type="string", example="기본 기능을 제공하는 요금제입니다.", nullable=true, description="설명"),
* @OA\Property(property="price", type="number", format="float", example=29000, description="가격"),
* @OA\Property(property="billing_cycle", type="string", enum={"monthly","yearly","lifetime"}, example="monthly", description="결제 주기"),
* @OA\Property(property="billing_cycle_label", type="string", example="월간", description="결제 주기 라벨"),
* @OA\Property(property="features", type="array", @OA\Items(type="string"), example={"사용자 5명","저장공간 10GB"}, nullable=true, description="기능 목록"),
* @OA\Property(property="is_active", type="boolean", example=true, description="활성 여부"),
* @OA\Property(property="formatted_price", type="string", example="29,000원", description="포맷된 가격"),
* @OA\Property(property="active_subscriptions_count", type="integer", example=15, description="활성 구독 수"),
* @OA\Property(property="created_at", type="string", format="date-time"),
* @OA\Property(property="updated_at", type="string", format="date-time")
* )
*
* @OA\Schema(
* schema="PlanCreateRequest",
* type="object",
* required={"name","code","price","billing_cycle"},
* description="요금제 등록 요청",
*
* @OA\Property(property="name", type="string", example="스타터", maxLength=100, description="요금제명"),
* @OA\Property(property="code", type="string", example="starter", maxLength=50, description="요금제 코드 (unique)"),
* @OA\Property(property="description", type="string", example="기본 기능을 제공하는 요금제입니다.", maxLength=500, nullable=true, description="설명"),
* @OA\Property(property="price", type="number", format="float", example=29000, minimum=0, description="가격"),
* @OA\Property(property="billing_cycle", type="string", enum={"monthly","yearly","lifetime"}, example="monthly", description="결제 주기"),
* @OA\Property(property="features", type="array", @OA\Items(type="string", maxLength=200), example={"사용자 5명","저장공간 10GB"}, nullable=true, description="기능 목록"),
* @OA\Property(property="is_active", type="boolean", example=true, description="활성 여부")
* )
*
* @OA\Schema(
* schema="PlanUpdateRequest",
* type="object",
* description="요금제 수정 요청",
*
* @OA\Property(property="name", type="string", example="스타터", maxLength=100, description="요금제명"),
* @OA\Property(property="code", type="string", example="starter", maxLength=50, description="요금제 코드"),
* @OA\Property(property="description", type="string", example="기본 기능을 제공하는 요금제입니다.", maxLength=500, nullable=true, description="설명"),
* @OA\Property(property="price", type="number", format="float", example=29000, minimum=0, description="가격"),
* @OA\Property(property="billing_cycle", type="string", enum={"monthly","yearly","lifetime"}, example="monthly", description="결제 주기"),
* @OA\Property(property="features", type="array", @OA\Items(type="string", maxLength=200), nullable=true, description="기능 목록"),
* @OA\Property(property="is_active", type="boolean", description="활성 여부")
* )
*/
class PlanApi
{
/**
* @OA\Get(
* path="/api/v1/plans",
* tags={"Plans"},
* summary="요금제 목록 조회",
* description="요금제 목록을 조회합니다. (관리자용)",
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
*
* @OA\Parameter(name="is_active", in="query", description="활성 상태 필터", @OA\Schema(type="boolean")),
* @OA\Parameter(name="billing_cycle", in="query", description="결제 주기", @OA\Schema(type="string", enum={"monthly","yearly","lifetime"})),
* @OA\Parameter(name="search", in="query", description="검색어 (이름, 코드, 설명)", @OA\Schema(type="string", maxLength=100)),
* @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"price","name","created_at"}, default="price")),
* @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="asc")),
* @OA\Parameter(ref="#/components/parameters/Page"),
* @OA\Parameter(ref="#/components/parameters/Size"),
*
* @OA\Response(
* response=200,
* description="조회 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(
* property="data",
* type="object",
* @OA\Property(property="current_page", type="integer", example=1),
* @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Plan")),
* @OA\Property(property="per_page", type="integer", example=20),
* @OA\Property(property="total", type="integer", example=5)
* )
* )
* }
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function index() {}
/**
* @OA\Get(
* path="/api/v1/plans/active",
* tags={"Plans"},
* summary="활성 요금제 목록",
* description="활성화된 요금제 목록을 조회합니다. (공개용)",
* security={{"ApiKeyAuth":{}}},
*
* @OA\Response(
* response=200,
* description="조회 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Plan"))
* )
* }
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function active() {}
/**
* @OA\Post(
* path="/api/v1/plans",
* tags={"Plans"},
* summary="요금제 등록",
* description="새로운 요금제를 등록합니다.",
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(ref="#/components/schemas/PlanCreateRequest")
* ),
*
* @OA\Response(
* response=201,
* description="등록 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(property="data", ref="#/components/schemas/Plan")
* )
* }
* )
* ),
*
* @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=422, description="유효성 검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function store() {}
/**
* @OA\Get(
* path="/api/v1/plans/{id}",
* tags={"Plans"},
* summary="요금제 상세 조회",
* description="요금제 상세 정보를 조회합니다.",
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
*
* @OA\Parameter(name="id", in="path", required=true, description="요금제 ID", @OA\Schema(type="integer")),
*
* @OA\Response(
* response=200,
* description="조회 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(property="data", ref="#/components/schemas/Plan")
* )
* }
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=404, description="요금제 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function show() {}
/**
* @OA\Put(
* path="/api/v1/plans/{id}",
* tags={"Plans"},
* summary="요금제 수정",
* description="요금제 정보를 수정합니다.",
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
*
* @OA\Parameter(name="id", in="path", required=true, description="요금제 ID", @OA\Schema(type="integer")),
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(ref="#/components/schemas/PlanUpdateRequest")
* ),
*
* @OA\Response(
* response=200,
* description="수정 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(property="data", ref="#/components/schemas/Plan")
* )
* }
* )
* ),
*
* @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=404, description="요금제 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=422, description="유효성 검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function update() {}
/**
* @OA\Delete(
* path="/api/v1/plans/{id}",
* tags={"Plans"},
* summary="요금제 삭제",
* description="요금제를 삭제합니다. 활성 구독이 있으면 삭제할 수 없습니다. (Soft Delete)",
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
*
* @OA\Parameter(name="id", in="path", required=true, description="요금제 ID", @OA\Schema(type="integer")),
*
* @OA\Response(
* response=200,
* description="삭제 성공",
*
* @OA\JsonContent(ref="#/components/schemas/ApiResponse")
* ),
*
* @OA\Response(response=400, description="활성 구독 존재", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=404, description="요금제 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function destroy() {}
/**
* @OA\Patch(
* path="/api/v1/plans/{id}/toggle",
* tags={"Plans"},
* summary="요금제 활성/비활성 토글",
* description="요금제의 활성 상태를 토글합니다.",
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
*
* @OA\Parameter(name="id", in="path", required=true, description="요금제 ID", @OA\Schema(type="integer")),
*
* @OA\Response(
* response=200,
* description="토글 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(property="data", ref="#/components/schemas/Plan")
* )
* }
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=404, description="요금제 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function toggle() {}
}
Reference in New Issue View Git Blame Copy Permalink