[TEST] API 문서 테스트 공통 기반 구축

[GiJungPark]

Description

작업 배경

#584에서 REST Docs 결과를 OpenAPI 명세로 생성하고 Swagger UI에 제공하는 환경을 구축한 뒤에도, Controller마다 MockMvc·인증 헤더·공통 응답 문서화를 반복하면 테스트 구조와 명세 표현이 쉽게 달라질 수 있습니다.

#574에서 마련하는 실제 형식의 테스트 Access Token과 Controller 인증 요청 기반을 문서 테스트에서도 재사용할 수 있도록 공통 구성을 정리합니다.

목표 상태

• Controller 문서 테스트가 동일한 MockMvc REST Docs 설정을 재사용합니다.
• 실제 형식의 테스트 Access Token을 Bearer 헤더에 적용할 수 있습니다.
• 공통 성공·오류 응답과 인증 오류를 일관된 형식으로 문서화합니다.
• 후속 도메인 문서화 작업이 공통 fixture 위에서 독립적으로 진행될 수 있습니다.

작업 범위

• 재사용 가능한 MockMvc REST Docs 테스트 구성 또는 기반 클래스 정의
• 요청·응답 pretty print와 공통 전처리 설정
• 테스트 Access Token 생성 및 Authorization Bearer 헤더 적용 도구 연결
• OpenAPI Bearer 인증 scheme과 인증 필요 operation 표현
• 공통 응답 envelope 및 오류 응답 field descriptor 정의
• path parameter, query parameter, request·response field 문서화 공통 규칙 정리
• REST Docs identifier와 snippet 디렉터리 명명 규칙 정의
• 민감한 토큰·개인정보가 문서 예시에 노출되지 않도록 처리
• 대표 API로 AuthController.logout의 정상·인증 실패 문서 테스트 적용
• 생성된 OpenAPI 명세에 대표 endpoint, security, request·response가 반영되는지 검증

제외 범위

• 모든 Controller 문서 테스트 전환
• 인증 외 도메인의 세부 field descriptor 정의
• 프로덕션 API 경로·요청·응답 변경
• 문서화를 위한 프로덕션 Controller 또는 Application 리팩터링
• 실제 DB, Redis, Kakao 및 Apple 호출
• REST Docs/OpenAPI Gradle 환경 재구성
• 테스트 실패를 우회하기 위한 로컬 application-*.yml 생성

완료 조건

• 후속 Controller 문서 테스트가 공통 설정과 인증 요청 도구를 재사용할 수 있습니다.
• 실제 형식의 Access Token을 사용한 대표 인증 API 문서 테스트가 통과합니다.
• 대표 operation이 OpenAPI 명세에 Bearer 인증 요구사항과 함께 생성됩니다.
• 정상 응답과 기존 인증 오류 응답 형식이 문서에 반영됩니다.
• 공통 descriptor와 전처리 설정이 Controller 테스트마다 중복되지 않습니다.
• 문서 예시에 실제 Secret, Access Token 및 개인정보가 포함되지 않습니다.
• 외부 DB, Redis 및 소셜 API 없이 관련 문서 테스트가 실행됩니다.
• ./gradlew build -x test와 관련 문서 생성 테스트가 성공합니다.

To-Do

• MockMvc REST Docs 공통 구성 추가
• 요청·응답 공통 전처리 설정
• 테스트 Access Token과 Bearer 요청 도구 연결
• OpenAPI Bearer 인증 scheme 구성
• 공통 성공·오류 응답 descriptor 정의
• snippet identifier 및 디렉터리 규칙 정의
• AuthController.logout 대표 문서 테스트 작성
• 생성 OpenAPI 명세 반영 검증
• 민감 정보 노출 여부 확인

Reference

• Depends on [CHORE] REST Docs 기반 OpenAPI 생성 환경 구축 #584
• Reuses [TEST] 인증 Controller 테스트에 Access Token 적용 기반 마련 #574
• Follow-up to [REFACTOR] 로그인 및 토큰 인증 구조 개선 #554