253 lines
10 KiB
PHP
253 lines
10 KiB
PHP
<?php
|
|
|
|
namespace App\Swagger\v1;
|
|
|
|
/**
|
|
* @OA\Tag(name="Category", description="카테고리 관리")
|
|
*
|
|
* @OA\Schema(
|
|
* schema="Category",
|
|
* type="object",
|
|
* required={"id","name"},
|
|
* @OA\Property(property="id", type="integer", example=12),
|
|
* @OA\Property(property="tenant_id", type="integer", example=1),
|
|
* @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
|
|
* @OA\Property(property="code", type="string", nullable=true, example="ELC"),
|
|
* @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="CategoryPagination",
|
|
* type="object",
|
|
* @OA\Property(property="current_page", type="integer", example=1),
|
|
* @OA\Property(
|
|
* property="data",
|
|
* type="array",
|
|
* @OA\Items(ref="#/components/schemas/Category")
|
|
* ),
|
|
* @OA\Property(property="first_page_url", type="string", example="/api/v1/categories?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/categories?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="« Previous"),
|
|
* @OA\Property(property="active", type="boolean", example=false)
|
|
* )
|
|
* ),
|
|
* @OA\Property(property="next_page_url", type="string", nullable=true, example="/api/v1/categories?page=2"),
|
|
* @OA\Property(property="path", type="string", example="/api/v1/categories"),
|
|
* @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="CategoryCreateRequest",
|
|
* type="object",
|
|
* required={"name"},
|
|
* @OA\Property(property="parent_id", type="integer", nullable=true),
|
|
* @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", example=true),
|
|
* @OA\Property(property="sort_order", type="integer", example=0)
|
|
* )
|
|
*
|
|
* @OA\Schema(
|
|
* schema="CategoryUpdateRequest",
|
|
* type="object",
|
|
* @OA\Property(property="parent_id", type="integer", nullable=true),
|
|
* @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")
|
|
* )
|
|
*
|
|
* @OA\Schema(
|
|
* schema="CategoryTreeNode",
|
|
* type="object",
|
|
* @OA\Property(property="id", type="integer", example=1),
|
|
* @OA\Property(property="code", type="string", nullable=true, example="ELC"),
|
|
* @OA\Property(property="name", type="string", example="전자"),
|
|
* @OA\Property(property="is_active", type="integer", example=1),
|
|
* @OA\Property(property="sort_order", type="integer", example=0),
|
|
* @OA\Property(property="children", type="array", @OA\Items(ref="#/components/schemas/CategoryTreeNode"))
|
|
* )
|
|
*/
|
|
class CategoryApi
|
|
{
|
|
/**
|
|
* @OA\Get(
|
|
* path="/api/v1/categories",
|
|
* tags={"Category"},
|
|
* summary="카테고리 목록",
|
|
* 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="parent_id", in="query", @OA\Schema(type="integer", nullable=true)),
|
|
* @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/CategoryPagination"))
|
|
* })
|
|
* ),
|
|
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function index() {}
|
|
|
|
/**
|
|
* @OA\Get(
|
|
* path="/api/v1/categories/{id}",
|
|
* tags={"Category"},
|
|
* 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/Category"))
|
|
* })
|
|
* ),
|
|
* @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function show() {}
|
|
|
|
/**
|
|
* @OA\Post(
|
|
* path="/api/v1/categories",
|
|
* tags={"Category"},
|
|
* summary="카테고리 생성",
|
|
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/CategoryCreateRequest")),
|
|
* @OA\Response(response=200, description="생성 성공",
|
|
* @OA\JsonContent(allOf={
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Category"))
|
|
* })
|
|
* ),
|
|
* @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function store() {}
|
|
|
|
/**
|
|
* @OA\Patch(
|
|
* path="/api/v1/categories/{id}",
|
|
* tags={"Category"},
|
|
* 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/CategoryUpdateRequest")),
|
|
* @OA\Response(response=200, description="수정 성공",
|
|
* @OA\JsonContent(allOf={
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Category"))
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function update() {}
|
|
|
|
/**
|
|
* @OA\Delete(
|
|
* path="/api/v1/categories/{id}",
|
|
* tags={"Category"},
|
|
* 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"))
|
|
* )
|
|
*/
|
|
public function destroy() {}
|
|
|
|
/**
|
|
* @OA\Post(
|
|
* path="/api/v1/categories/{id}/toggle",
|
|
* tags={"Category"},
|
|
* 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/Category"))
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function toggle() {}
|
|
|
|
/**
|
|
* @OA\Patch(
|
|
* path="/api/v1/categories/{id}/move",
|
|
* tags={"Category"},
|
|
* summary="부모/순서 이동",
|
|
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(
|
|
* type="object",
|
|
* @OA\Property(property="parent_id", type="integer", nullable=true),
|
|
* @OA\Property(property="sort_order", type="integer", nullable=true)
|
|
* )),
|
|
* @OA\Response(response=200, description="이동 성공",
|
|
* @OA\JsonContent(allOf={
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Category"))
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function move() {}
|
|
|
|
/**
|
|
* @OA\Post(
|
|
* path="/api/v1/categories/reorder",
|
|
* tags={"Category"},
|
|
* summary="정렬순서 일괄 변경",
|
|
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(
|
|
* type="object",
|
|
* @OA\Property(property="items", type="array", @OA\Items(
|
|
* type="object",
|
|
* @OA\Property(property="id", type="integer", example=1),
|
|
* @OA\Property(property="sort_order", type="integer", example=10)
|
|
* ))
|
|
* )),
|
|
* @OA\Response(response=200, description="저장 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse"))
|
|
* )
|
|
*/
|
|
public function reorder() {}
|
|
|
|
/**
|
|
* @OA\Get(
|
|
* path="/api/v1/categories/tree",
|
|
* tags={"Category"},
|
|
* summary="카테고리 트리",
|
|
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
|
|
* @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", type="array", @OA\Items(ref="#/components/schemas/CategoryTreeNode")))
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function tree() {}
|
|
}
|