refactor: Controller에서 Swagger 어노테이션 분리

- EstimateController에서 Swagger 어노테이션 제거 → EstimateApi.php 생성
- CommonController에서 Swagger 어노테이션 제거 → CommonApi.php 업데이트
- TenantFieldSettingController에서 Swagger 어노테이션 제거 → TenantFieldSettingApi.php 생성
- Swagger 정책 준수: Controller는 비즈니스 로직만, Swagger는 별도 파일로 분리

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

app/Http/Controllers/Api/V1/CommonController.php

@@ -6,49 +6,8 @@
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
 
-/**
- * @OA\Tag(
- *     name="Settings - Common Codes",
- *     description="공통 코드 관리 API"
- * )
- */
 class CommonController
 {
-    /**
-     * @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(
-     *                     type="object",
-     *
-     *                     @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)
-     *                 )
-     *             )
-     *         )
-     *     )
-     * )
-     */
     public static function getComeCode()
     {
         return ApiResponse::handle(function () {
@@ -59,20 +18,6 @@ public static 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(Request $request)
     {
         return ApiResponse::handle(function () {
@@ -81,29 +26,6 @@ public function list(Request $request)
         }, __('message.fetched'));
     }
 
-    /**
-     * @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(Request $request, string $group)
     {
         return ApiResponse::handle(function () {
@@ -112,51 +34,6 @@ public function index(Request $request, string $group)
         }, __('message.fetched'));
     }
 
-    /**
-     * @OA\Post(
-     *     path="/api/v1/settings/common",
-     *     summary="공통 코드 생성",
-     *     description="새로운 공통 코드를 생성합니다.",
-     *     tags={"Settings - Common Codes"},
-     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
-     *
-     *     @OA\RequestBody(
-     *         required=true,
-     *
-     *         @OA\JsonContent(
-     *             type="object",
-     *
-     *             @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\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(Request $request)
     {
         return ApiResponse::handle(function () {
@@ -165,58 +42,6 @@ public function store(Request $request)
         }, __('message.settings.common_code_saved'));
     }
 
-    /**
-     * @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(
-     *             type="object",
-     *
-     *             @OA\Property(property="name", type="string", example="수정된 이름"),
-     *             @OA\Property(property="description", type="string", example="수정된 설명")
-     *         )
-     *     ),
-     *
-     *     @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(Request $request, int $id)
     {
         return ApiResponse::handle(function () {
@@ -225,40 +50,6 @@ public function update(Request $request, int $id)
         }, __('message.updated'));
     }
 
-    /**
-     * @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(Request $request, int $id)
     {
         return ApiResponse::handle(function () {
@@ -266,4 +57,4 @@ public function destroy(Request $request, int $id)
             return [];
         }, __('message.deleted'));
     }
-}
+}

app/Http/Controllers/Api/V1/EstimateController.php

@@ -9,9 +9,6 @@
 use App\Services\Estimate\EstimateService;
 use Illuminate\Http\Request;
 
-/**
- * @OA\Tag(name="Estimate", description="견적 관리 API")
- */
 class EstimateController extends Controller
 {
     protected EstimateService $estimateService;
@@ -21,24 +18,6 @@ public function __construct(EstimateService $estimateService)
         $this->estimateService = $estimateService;
     }
 
-    /**
-     * @OA\Get(
-     *     path="/v1/estimates",
-     *     summary="견적 목록 조회",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\Parameter(name="status", in="query", description="견적 상태", @OA\Schema(type="string")),
-     *     @OA\Parameter(name="customer_name", in="query", description="고객명", @OA\Schema(type="string")),
-     *     @OA\Parameter(name="model_set_id", in="query", description="모델셋 ID", @OA\Schema(type="integer")),
-     *     @OA\Parameter(name="date_from", in="query", description="시작일", @OA\Schema(type="string", format="date")),
-     *     @OA\Parameter(name="date_to", in="query", description="종료일", @OA\Schema(type="string", format="date")),
-     *     @OA\Parameter(name="search", in="query", description="검색어", @OA\Schema(type="string")),
-     *     @OA\Parameter(name="per_page", in="query", description="페이지당 항목수", @OA\Schema(type="integer", default=20)),
-     *
-     *     @OA\Response(response=200, description="성공")
-     * )
-     */
     public function index(Request $request)
     {
         $estimates = $this->estimateService->getEstimates($request->all());
@@ -48,18 +27,6 @@ public function index(Request $request)
         ], __('message.fetched'));
     }
 
-    /**
-     * @OA\Get(
-     *     path="/v1/estimates/{id}",
-     *     summary="견적 상세 조회",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
-     *
-     *     @OA\Response(response=200, description="성공")
-     * )
-     */
     public function show($id)
     {
         $estimate = $this->estimateService->getEstimateDetail($id);
@@ -69,31 +36,6 @@ public function show($id)
         ], __('message.fetched'));
     }
 
-    /**
-     * @OA\Post(
-     *     path="/v1/estimates",
-     *     summary="견적 생성",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\RequestBody(
-     *         required=true,
-     *
-     *         @OA\JsonContent(
-     *             required={"model_set_id", "estimate_name", "parameters"},
-     *
-     *             @OA\Property(property="model_set_id", type="integer", description="모델셋 ID"),
-     *             @OA\Property(property="estimate_name", type="string", description="견적명"),
-     *             @OA\Property(property="customer_name", type="string", description="고객명"),
-     *             @OA\Property(property="project_name", type="string", description="프로젝트명"),
-     *             @OA\Property(property="parameters", type="object", description="견적 파라미터"),
-     *             @OA\Property(property="notes", type="string", description="비고")
-     *         )
-     *     ),
-     *
-     *     @OA\Response(response=201, description="생성 성공")
-     * )
-     */
     public function store(CreateEstimateRequest $request)
     {
         $estimate = $this->estimateService->createEstimate($request->validated());
@@ -103,32 +45,6 @@ public function store(CreateEstimateRequest $request)
         ], __('message.created'), 201);
     }
 
-    /**
-     * @OA\Put(
-     *     path="/v1/estimates/{id}",
-     *     summary="견적 수정",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
-     *
-     *     @OA\RequestBody(
-     *         required=true,
-     *
-     *         @OA\JsonContent(
-     *
-     *             @OA\Property(property="estimate_name", type="string", description="견적명"),
-     *             @OA\Property(property="customer_name", type="string", description="고객명"),
-     *             @OA\Property(property="project_name", type="string", description="프로젝트명"),
-     *             @OA\Property(property="parameters", type="object", description="견적 파라미터"),
-     *             @OA\Property(property="status", type="string", description="견적 상태"),
-     *             @OA\Property(property="notes", type="string", description="비고")
-     *         )
-     *     ),
-     *
-     *     @OA\Response(response=200, description="수정 성공")
-     * )
-     */
     public function update(UpdateEstimateRequest $request, $id)
     {
         $estimate = $this->estimateService->updateEstimate($id, $request->validated());
@@ -138,18 +54,6 @@ public function update(UpdateEstimateRequest $request, $id)
         ], __('message.updated'));
     }
 
-    /**
-     * @OA\Delete(
-     *     path="/v1/estimates/{id}",
-     *     summary="견적 삭제",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
-     *
-     *     @OA\Response(response=200, description="삭제 성공")
-     * )
-     */
     public function destroy($id)
     {
         $this->estimateService->deleteEstimate($id);
@@ -157,31 +61,6 @@ public function destroy($id)
         return ApiResponse::success([], __('message.deleted'));
     }
 
-    /**
-     * @OA\Post(
-     *     path="/v1/estimates/{id}/clone",
-     *     summary="견적 복제",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
-     *
-     *     @OA\RequestBody(
-     *         required=true,
-     *
-     *         @OA\JsonContent(
-     *             required={"estimate_name"},
-     *
-     *             @OA\Property(property="estimate_name", type="string", description="새 견적명"),
-     *             @OA\Property(property="customer_name", type="string", description="고객명"),
-     *             @OA\Property(property="project_name", type="string", description="프로젝트명"),
-     *             @OA\Property(property="notes", type="string", description="비고")
-     *         )
-     *     ),
-     *
-     *     @OA\Response(response=201, description="복제 성공")
-     * )
-     */
     public function clone(Request $request, $id)
     {
         $request->validate([
@@ -198,29 +77,6 @@ public function clone(Request $request, $id)
         ], __('message.estimate.cloned'), 201);
     }
 
-    /**
-     * @OA\Put(
-     *     path="/v1/estimates/{id}/status",
-     *     summary="견적 상태 변경",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
-     *
-     *     @OA\RequestBody(
-     *         required=true,
-     *
-     *         @OA\JsonContent(
-     *             required={"status"},
-     *
-     *             @OA\Property(property="status", type="string", enum={"DRAFT","SENT","APPROVED","REJECTED","EXPIRED"}, description="변경할 상태"),
-     *             @OA\Property(property="notes", type="string", description="상태 변경 사유")
-     *         )
-     *     ),
-     *
-     *     @OA\Response(response=200, description="상태 변경 성공")
-     * )
-     */
     public function changeStatus(Request $request, $id)
     {
         $request->validate([
@@ -239,18 +95,6 @@ public function changeStatus(Request $request, $id)
         ], __('message.estimate.status_changed'));
     }
 
-    /**
-     * @OA\Get(
-     *     path="/v1/estimates/form-schema/{model_set_id}",
-     *     summary="견적 폼 스키마 조회",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\Parameter(name="model_set_id", in="path", required=true, description="모델셋 ID", @OA\Schema(type="integer")),
-     *
-     *     @OA\Response(response=200, description="성공")
-     * )
-     */
     public function getFormSchema($modelSetId)
     {
         $schema = $this->estimateService->getEstimateFormSchema($modelSetId);
@@ -260,28 +104,6 @@ public function getFormSchema($modelSetId)
         ], __('message.fetched'));
     }
 
-    /**
-     * @OA\Post(
-     *     path="/v1/estimates/preview/{model_set_id}",
-     *     summary="견적 계산 미리보기",
-     *     tags={"Estimate"},
-     *     security={{"bearerAuth": {}}},
-     *
-     *     @OA\Parameter(name="model_set_id", in="path", required=true, description="모델셋 ID", @OA\Schema(type="integer")),
-     *
-     *     @OA\RequestBody(
-     *         required=true,
-     *
-     *         @OA\JsonContent(
-     *             required={"parameters"},
-     *
-     *             @OA\Property(property="parameters", type="object", description="견적 파라미터")
-     *         )
-     *     ),
-     *
-     *     @OA\Response(response=200, description="계산 성공")
-     * )
-     */
     public function previewCalculation(Request $request, $modelSetId)
     {
         $request->validate([

app/Http/Controllers/Api/V1/TenantFieldSettingController.php

@@ -7,47 +7,8 @@
 use App\Services\TenantFieldSettingService;
 use Illuminate\Http\Request;
 
-/**
- * @OA\Tag(
- *     name="Settings - Fields",
- *     description="테넌트 필드 설정 관리 API"
- * )
- */
 class TenantFieldSettingController extends Controller
 {
-    /**
-     * @OA\Get(
-     *     path="/api/v1/settings/fields",
-     *     summary="테넌트 필드 설정 목록 조회",
-     *     description="전역 + 테넌트별 병합된 필드 설정 효과값을 조회합니다.",
-     *     tags={"Settings - Fields"},
-     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
-     *
-     *     @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(
-     *                     type="object",
-     *
-     *                     @OA\Property(property="field_key", type="string", example="product_name_required"),
-     *                     @OA\Property(property="field_value", type="string", example="true"),
-     *                     @OA\Property(property="source", type="string", example="tenant", description="global 또는 tenant")
-     *                 )
-     *             )
-     *         )
-     *     )
-     * )
-     */
     public function index(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
@@ -55,61 +16,6 @@ public function index(Request $request)
         }, '테넌트 필드 효과값 목록 조회');
     }
 
-    /**
-     * @OA\Put(
-     *     path="/api/v1/settings/fields/bulk",
-     *     summary="테넌트 필드 설정 대량 저장",
-     *     description="여러 필드 설정을 트랜잭션으로 일괄 저장합니다.",
-     *     tags={"Settings - Fields"},
-     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
-     *
-     *     @OA\RequestBody(
-     *         required=true,
-     *
-     *         @OA\JsonContent(
-     *             type="object",
-     *
-     *             @OA\Property(
-     *                 property="fields",
-     *                 type="array",
-     *
-     *                 @OA\Items(
-     *                     type="object",
-     *
-     *                     @OA\Property(property="field_key", type="string", example="product_name_required"),
-     *                     @OA\Property(property="field_value", type="string", example="true")
-     *                 )
-     *             )
-     *         )
-     *     ),
-     *
-     *     @OA\Response(
-     *         response=200,
-     *         description="대량 저장 성공",
-     *
-     *         @OA\JsonContent(ref="#/components/schemas/ApiResponse")
-     *     ),
-     *
-     *     @OA\Response(
-     *         response=400,
-     *         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 bulkUpsert(Request $request)
     {
         return ApiResponse::handle(function () use ($request) {
@@ -117,69 +23,10 @@ public function bulkUpsert(Request $request)
         }, '테넌트 필드 설정 대량 저장');
     }
 
-    /**
-     * @OA\Patch(
-     *     path="/api/v1/settings/fields/{key}",
-     *     summary="테넌트 필드 설정 단건 수정",
-     *     description="특정 필드 설정을 개별적으로 수정합니다.",
-     *     tags={"Settings - Fields"},
-     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
-     *
-     *     @OA\Parameter(
-     *         name="key",
-     *         in="path",
-     *         required=true,
-     *         description="필드 키",
-     *
-     *         @OA\Schema(type="string", example="product_name_required")
-     *     ),
-     *
-     *     @OA\RequestBody(
-     *         required=true,
-     *
-     *         @OA\JsonContent(
-     *             type="object",
-     *
-     *             @OA\Property(property="field_value", type="string", example="false")
-     *         )
-     *     ),
-     *
-     *     @OA\Response(
-     *         response=200,
-     *         description="필드 설정 수정 성공",
-     *
-     *         @OA\JsonContent(ref="#/components/schemas/ApiResponse")
-     *     ),
-     *
-     *     @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=400,
-     *         description="유효하지 않은 필드 타입",
-     *
-     *         @OA\JsonContent(
-     *             type="object",
-     *
-     *             @OA\Property(property="success", type="boolean", example=false),
-     *             @OA\Property(property="message", type="string", example="유효하지 않은 필드 타입입니다.")
-     *         )
-     *     )
-     * )
-     */
     public function updateOne(Request $request, string $key)
     {
         return ApiResponse::handle(function () use ($request, $key) {
             return TenantFieldSettingService::updateOne($key, $request->all());
         }, '테넌트 필드 설정 단건 수정');
     }
-}
+}