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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Settings - Common Codes",
 *     description="공통 코드 관리 API"
 * )
 *
 * @OA\Schema(
 *     schema="CommonCode",
 *
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="code_group", type="string", example="product_type"),
 *     @OA\Property(property="code", type="string", example="PRODUCT"),
 *     @OA\Property(property="name", type="string", example="제품"),
 *     @OA\Property(property="description", type="string", example="완제품"),
 *     @OA\Property(property="is_active", type="boolean", example=true)
 * )
 *
 * @OA\Schema(
 *     schema="CommonCodeCreateRequest",
 *     required={"code_group", "code", "name"},
 *
 *     @OA\Property(property="code_group", type="string", example="product_type"),
 *     @OA\Property(property="code", type="string", example="SERVICE"),
 *     @OA\Property(property="name", type="string", example="서비스"),
 *     @OA\Property(property="description", type="string", example="서비스 상품")
 * )
 *
 * @OA\Schema(
 *     schema="CommonCodeUpdateRequest",
 *
 *     @OA\Property(property="name", type="string", example="수정된 이름"),
 *     @OA\Property(property="description", type="string", example="수정된 설명")
 * )
 */
class CommonApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/settings/common/code",
     *     summary="공통 코드 조회",
     *     description="테넌트의 활성화된 공통 코드 목록을 조회합니다.",
     *     tags={"Settings - Common Codes"},
     *     security={{"ApiKeyAuth": {}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="공통 코드 조회 성공",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="공통코드"),
     *             @OA\Property(
     *                 property="data",
     *                 type="array",
     *
     *                 @OA\Items(ref="#/components/schemas/CommonCode")
     *             )
     *         )
     *     )
     * )
     */
    public function getComeCode() {}

    /**
     * @OA\Get(
     *     path="/api/v1/settings/common",
     *     summary="공통 코드 목록 조회",
     *     description="전체 공통 코드 목록을 조회합니다.",
     *     tags={"Settings - Common Codes"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="공통 코드 목록 조회 성공"
     *     )
     * )
     */
    public function list() {}

    /**
     * @OA\Get(
     *     path="/api/v1/settings/common/{group}",
     *     summary="특정 그룹 공통 코드 조회",
     *     description="특정 그룹의 공통 코드 목록을 조회합니다.",
     *     tags={"Settings - Common Codes"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="group",
     *         in="path",
     *         required=true,
     *         description="코드 그룹",
     *
     *         @OA\Schema(type="string", example="product_type")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="그룹 코드 조회 성공"
     *     )
     * )
     */
    public function index() {}

    /**
     * @OA\Post(
     *     path="/api/v1/settings/common",
     *     summary="공통 코드 생성",
     *     description="새로운 공통 코드를 생성합니다.",
     *     tags={"Settings - Common Codes"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/CommonCodeCreateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="공통 코드 생성 성공"
     *     ),
     *     @OA\Response(
     *         response=409,
     *         description="중복된 공통 코드",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="중복된 공통 코드가 존재합니다.")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=422,
     *         description="유효성 검사 실패",
     *
     *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
     *     )
     * )
     */
    public function store() {}

    /**
     * @OA\Patch(
     *     path="/api/v1/settings/common/{id}",
     *     summary="공통 코드 수정",
     *     description="기존 공통 코드를 수정합니다.",
     *     tags={"Settings - Common Codes"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         description="공통 코드 ID",
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/CommonCodeUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="공통 코드 수정 성공"
     *     ),
     *     @OA\Response(
     *         response=404,
     *         description="공통 코드를 찾을 수 없음",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="해당 공통 코드를 찾을 수 없습니다.")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=422,
     *         description="유효성 검사 실패",
     *
     *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
     *     )
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/settings/common/{id}",
     *     summary="공통 코드 삭제",
     *     description="공통 코드를 삭제합니다.",
     *     tags={"Settings - Common Codes"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         description="공통 코드 ID",
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="공통 코드 삭제 성공"
     *     ),
     *     @OA\Response(
     *         response=404,
     *         description="공통 코드를 찾을 수 없음",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="해당 공통 코드를 찾을 수 없습니다.")
     *         )
     *     )
     * )
     */
    public function destroy() {}
}