이번 게시글에선 "Controller 레이어와 문서화 (Swagger / OpenAPI) 어노테이션 분리 전략"에 대해서 말하려고 한다.

✅ 왜 Interface로 따로 분리를 선택했나

1️⃣ 코드 가독성/책임 분리

컨트롤러 파일에 @Operation, @Parameter, @ApiResponses 등 Swagger 문서용 어노테이션이 많아지면,
👉 비즈니스 로직 코드보다 문서용 어노테이션 코드가 더 많아짐 → 가독성이 떨어짐

인터페이스로 문서화를 따로 분리한다면???

컨트롤러 클래스는 → 비즈니스 처리와 라우팅 담당
인터페이스 파일은 → API 명세 담당 (Swagger용 어노테이션만 모음)

2️⃣ 재사용성

같은 API 명세를 여러 컨트롤러에서 재사용 가능 (ex: BaseApi, CommonApi, AdminApi 등)

테스트에서도 interface 기반으로 문서 자동화를 쉽게 할 수 있다.

3️⃣ Swagger 문서 버전 관리/유지보수 편리

API Spec 변경시 → Interface 파일만 수정하면 됨
Controller 코드에는 영향이 최소화되어 유지보수에 좋다!!

---

✅ 구성 패턴 - V1

1️⃣ Interface 정의 (Api 명세 파일)

@SecurityRequirement(name = "bearerAuth")
@Tag(name = "Answer", description = "답변 관리 API")
public interface AnswerApi {

    @Operation(summary = "답변 생성", description = "새로운 답변을 생성합니다.")
    @PostMapping
    ResponseEntity<AnswerDetailResponse> createAnswer(...);

    @Operation(summary = "답변 삭제", description = "답변을 삭제합니다.")
    @DeleteMapping("/{answerId}")
    ResponseEntity<Void> deleteAnswer(@PathVariable Long answerId);

    // 기타 API...
}

👉 구현은 없음, API 시그니처 + 문서화 어노테이션만 존재

2️⃣ Controller 에서 구현

@RestController
@RequestMapping("/api/answers")
@RequiredArgsConstructor
public class AnswerController implements AnswerApi {

    private final AnswerService answerService;

    @Override
    public ResponseEntity<AnswerDetailResponse> createAnswer(...) {
        // 서비스 호출
    }

    @Override
    public ResponseEntity<Void> deleteAnswer(Long answerId) {
        // 서비스 호출
    }
}

👉 implements AnswerApi → 인터페이스에서 정의한 메서드를 오버라이드
👉 @RestController → 실질적인 요청 처리 담당

✅ 장점 정리

기존 방식 (@Operation 직접 컨트롤러에 작성)	Interface 분리 방식
컨트롤러 파일 복잡해짐	컨트롤러는 로직만 담당, 문서는 따로 관리
문서 변경 시 Controller도 수정 필요	Interface만 수정
테스트 / 리팩토링 시 영향 있음	책임 분리로 안정적
문서와 로직이 섞여 있음	리뷰 시 로직과 문서 분리로 편의성 ↑

---

✅ 추천 최적화 패턴 - V2

1️⃣ BaseApi 작성 (공통화)

@SecurityRequirement(name = "bearerAuth")
@Parameter(
    in = ParameterIn.HEADER,
    name = "Authorization", required = true,
    schema = @Schema(type = "string"),
    description = "Bearer [Access 토큰]"
)
public interface BaseApi {
}

👉 대부분 서비스에서는 로그인을 통한 인증 / 인가가 있기 때문에 공통된 토큰인증과 관련된 부분을 위와 같이 BaseApi로 만들어둔다.
그러면 하위 Api에서 반복 작성했던 Authorization 헤더/보안 설정 제거 가능!

2️⃣ 최적화된 AnswerApi 예시

@Tag(name = "Answer", description = "답변 관리 API")
public interface AnswerApi extends BaseApi {

    @Operation(summary = "답변 생성", description = "새로운 답변을 생성합니다.")
    @ApiResponse(responseCode = "201", description = "답변 생성 성공",
            content = @Content(mediaType = "application/json",
                    schema = @Schema(implementation = AnswerDetailResponse.class)))
    @PostMapping(value = "/members/{memberId}/answers", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    ResponseEntity<ApiResponse<AnswerDetailResponse>> createAnswer(
            @PathVariable Long memberId,
            @RequestPart(value = "imageFiles") MultipartFile imageFile,
            @RequestPart(name = "request") @Valid AnswerCreateRequest request);

    @Operation(summary = "답변 조회", description = "모든 답변을 페이지네이션으로 조회합니다.")
    @ApiResponse(responseCode = "200", description = "답변 조회 성공",
            content = @Content(mediaType = "application/json",
                    schema = @Schema(implementation = Page.class)))
    @GetMapping("/members/{memberId}/answers")
    ResponseEntity<ApiResponse<Page<AnswerDetailResponse>>> getAllAnswers(
            @PathVariable Long memberId,
            @RequestParam(required = false) Long category,
            Pageable pageable);
            
    ...
}

✅ 왜 @ApiResponse 작성하는가?

• Swagger 문서에서 응답 구조 미리 확인 가능
• 프론트 / 앱 개발자가 응답 구조 보고 개발 가능
• 에러 케이스도 공통 문서화 가능 (400, 401, 500 등)
• 유지보수 시 → API 명세 기반 자동 검증 가능

✅ 에러 케이스 문서화 예시

@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "답변 생성 성공",
            content = @Content(mediaType = "application/json",
                    schema = @Schema(implementation = AnswerDetailResponse.class))),
    @ApiResponse(responseCode = "400", description = "잘못된 요청",
            content = @Content(mediaType = "application/json",
                    schema = @Schema(implementation = ApiResponse.class))),
    @ApiResponse(responseCode = "401", description = "인증 실패"),
    @ApiResponse(responseCode = "500", description = "서버 오류")
})

3️⃣ 테스트 코드 작성

@AutoConfigureMockMvc
@SpringBootTest
@AutoConfigureRestDocs
class AnswerControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @DisplayName("답변 생성 API 테스트")
    void createAnswerTest() throws Exception {
        MockMultipartFile file = new MockMultipartFile("imageFiles", "test.png", "image/png", "test".getBytes());
        MockMultipartFile request = new MockMultipartFile("request", "", "application/json",
                "{\"title\":\"테스트 제목\", \"content\":\"테스트 내용\"}".getBytes());

        mockMvc.perform(multipart("/api/answers")
                        .file(file)
                        .file(request)
                        .header("Authorization", "Bearer dummy_token"))
                .andExpect(status().isCreated())
                .andDo(document("answer-create",
                        requestHeaders(
                                headerWithName("Authorization").description("Access Token")
                        ),
                        requestParts(
                                partWithName("imageFiles").description("업로드 파일"),
                                partWithName("request").description("답변 생성 요청 데이터")
                        ),
                        responseFields(
                                fieldWithPath("id").description("생성된 답변 ID"),
                                fieldWithPath("title").description("답변 제목"),
                                fieldWithPath("content").description("답변 내용")
                        )
                ));
    }
}

위와 같이 Mock을 사용하여 테스트 코드를 작성할 수 있다.
개발을 진행하고 학습을 진행할 수록 테스트 코드의 중요성에 대하여 느끼고 있다.
앞으로 테스트 코드에 대한 학습을 진행 후 컨트롤러 기반, 메소드 기반 등 세부 테스트 코드 작성을 적용해 볼 것이다.

---

최종 결론

컨트롤러와 문서화 설계 최적화 구조는

• BaseApi로 공통 어노테이션 통일
• @ApiResponse → 성공/에러 응답 명세 작성
• HTTP 메서드별 애노테이션 명확 사용
• DTO에 @Valid 적용 → 입력값 검증 가능

👉 "문서화와 비즈니스 로직 분리" 전략은 유지보수와 팀 협업에도 큰 도움이 될거라 생각하며 코드 가독성, 유지보수성, 테스트 용이성 모두에 도움이 되므로 다음 프로젝트에서 직접 적용해볼 계획이다!!