sam-api/app/Swagger/v1/ClassificationApi.php

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Classification", description="분류 관리 (평면 구조 / 코드 테이블)")
 *
 * @OA\Schema(
 *   schema="Classification",
 *   type="object",
 *   required={"id","group","name"},
 *
 *   @OA\Property(property="id", type="integer", example=11),
 *   @OA\Property(property="tenant_id", type="integer", example=1),
 *   @OA\Property(property="group", type="string", example="product_type"),
 *   @OA\Property(property="code", type="string", nullable=true, example="OUTER"),
 *   @OA\Property(property="name", type="string", example="아우터"),
 *   @OA\Property(property="description", type="string", nullable=true, example=null),
 *   @OA\Property(property="is_active", type="integer", example=1),
 *   @OA\Property(property="sort_order", type="integer", example=10),
 *   @OA\Property(property="created_at", type="string", example="2025-08-22 10:00:00"),
 *   @OA\Property(property="updated_at", type="string", example="2025-08-22 10:10:00")
 * )
 *
 * @OA\Schema(
 *   schema="ClassificationPagination",
 *   type="object",
 *   description="라라벨 LengthAwarePaginator 기본 구조",
 *
 *   @OA\Property(property="current_page", type="integer", example=1),
 *   @OA\Property(
 *     property="data",
 *     type="array",
 *
 *     @OA\Items(ref="#/components/schemas/Classification")
 *   ),
 *
 *   @OA\Property(property="first_page_url", type="string", example="/api/v1/classifications?page=1"),
 *   @OA\Property(property="from", type="integer", example=1),
 *   @OA\Property(property="last_page", type="integer", example=3),
 *   @OA\Property(property="last_page_url", type="string", example="/api/v1/classifications?page=3"),
 *   @OA\Property(
 *     property="links",
 *     type="array",
 *
 *     @OA\Items(type="object",
 *
 *       @OA\Property(property="url", type="string", nullable=true, example=null),
 *       @OA\Property(property="label", type="string", example="&laquo; Previous"),
 *       @OA\Property(property="active", type="boolean", example=false)
 *     )
 *   ),
 *   @OA\Property(property="next_page_url", type="string", nullable=true, example="/api/v1/classifications?page=2"),
 *   @OA\Property(property="path", type="string", example="/api/v1/classifications"),
 *   @OA\Property(property="per_page", type="integer", example=20),
 *   @OA\Property(property="prev_page_url", type="string", nullable=true, example=null),
 *   @OA\Property(property="to", type="integer", example=20),
 *   @OA\Property(property="total", type="integer", example=60)
 * )
 *
 * @OA\Schema(
 *   schema="ClassificationCreateRequest",
 *   type="object",
 *   required={"group","name"},
 *
 *   @OA\Property(property="group", type="string", maxLength=50, example="product_type"),
 *   @OA\Property(property="code", type="string", nullable=true, maxLength=50, example="OUTER"),
 *   @OA\Property(property="name", type="string", maxLength=100, example="아우터"),
 *   @OA\Property(property="description", type="string", nullable=true, maxLength=255),
 *   @OA\Property(property="is_active", type="boolean", example=true),
 *   @OA\Property(property="sort_order", type="integer", example=0)
 * )
 *
 * @OA\Schema(
 *   schema="ClassificationUpdateRequest",
 *   type="object",
 *
 *   @OA\Property(property="group", type="string", maxLength=50),
 *   @OA\Property(property="code", type="string", nullable=true, maxLength=50),
 *   @OA\Property(property="name", type="string", maxLength=100),
 *   @OA\Property(property="description", type="string", nullable=true, maxLength=255),
 *   @OA\Property(property="is_active", type="boolean"),
 *   @OA\Property(property="sort_order", type="integer")
 * )
 */
class ClassificationApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/classifications",
     *   tags={"Classification"},
     *   summary="분류 목록",
     *   description="그룹/검색/활성여부 조건으로 분류 목록을 페이징 반환합니다.",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="page", in="query", @OA\Schema(type="integer", example=1)),
     *   @OA\Parameter(name="size", in="query", @OA\Schema(type="integer", example=20)),
     *   @OA\Parameter(name="q", in="query", description="코드/이름 검색", @OA\Schema(type="string")),
     *   @OA\Parameter(name="group", in="query", description="분류 그룹 키", @OA\Schema(type="string")),
     *   @OA\Parameter(name="only_active", in="query", @OA\Schema(type="boolean")),
     *
     *   @OA\Response(
     *     response=200,
     *     description="조회 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ClassificationPagination"))
     *     })
     *   ),
     *
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *   path="/api/v1/classifications/{id}",
     *   tags={"Classification"},
     *   summary="분류 단건 조회",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @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/Classification"))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *   path="/api/v1/classifications",
     *   tags={"Classification"},
     *   summary="분류 생성",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ClassificationCreateRequest")),
     *
     *   @OA\Response(
     *     response=200,
     *     description="생성 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Classification"))
     *     })
     *   ),
     *
     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Patch(
     *   path="/api/v1/classifications/{id}",
     *   tags={"Classification"},
     *   summary="분류 수정",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ClassificationUpdateRequest")),
     *
     *   @OA\Response(
     *     response=200,
     *     description="수정 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Classification"))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/classifications/{id}",
     *   tags={"Classification"},
     *   summary="분류 삭제(soft)",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\Response(response=200, description="삭제 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function destroy() {}
}