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

<?php

namespace App\Swagger\v1;

/**
 * 제품 카테고리 스키마
 * @OA\Schema(
 *     schema="ProductCategory",
 *     type="object",
 *     description="제품 카테고리",
 *     required={"id","code_group","code","name","is_active","sort_order"},
 *     @OA\Property(property="id", type="integer", example=4),
 *     @OA\Property(property="code_group", type="string", example="category"),
 *     @OA\Property(property="code", type="string", example="BP"),
 *     @OA\Property(property="name", type="string", example="절곡판"),
 *     @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
 *     @OA\Property(
 *         property="attributes",
 *         type="object",
 *         nullable=true,
 *         description="카테고리 속성(자유형식 JSON)",
 *         example={"color":"blue","flags":{"screen":true}}
 *     ),
 *     @OA\Property(property="description", type="string", nullable=true, example="절곡판"),
 *     @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", format="date-time", example="2025-07-23T09:00:00+09:00"),
 *     @OA\Property(property="updated_at", type="string", format="date-time", example="2025-07-23T09:00:00+09:00")
 * )
 *
 * 카테고리 목록 조회
 * @OA\Get(
 *     path="/api/v1/product/category",
 *     summary="제품 카테고리 목록 조회",
 *     description="제품 카테고리(최상위: parent_id = null) 리스트를 반환합니다.",
 *     tags={"Product"},
 *     security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
 *     @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/ProductCategory")
 *                     )
 *                 )
 *             }
 *         )
 *     ),
 *     @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=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
 *     @OA\Response(response=404, description="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
 *     @OA\Response(response=405, description="허용되지 않는 메서드", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
 *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
 * )
 */
class ProductApi {}