[Docs] 에러 응답에 대한 문서화

leegwichan · web-flow · commit 2d3e86ffdd95 · 2025-07-10T10:38:37.000+09:00
diff --git a/src/test/java/eatda/document/BaseDocumentTest.java b/src/test/java/eatda/document/BaseDocumentTest.java
@@ -1,6 +1,11 @@
 package eatda.document;
 
+import static org.mockito.Mockito.doReturn;
+import static org.springframework.restdocs.payload.JsonFieldType.STRING;
+import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
+
 import eatda.controller.web.jwt.JwtManager;
+import eatda.exception.BusinessErrorCode;
 import eatda.service.auth.AuthService;
 import eatda.service.member.MemberService;
 import eatda.service.store.StoreService;
@@ -10,7 +15,6 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.junit.jupiter.MockitoExtension;
-import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.boot.test.web.server.LocalServerPort;
 import org.springframework.restdocs.RestDocumentationContextProvider;
@@ -24,15 +28,22 @@
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
 public abstract class BaseDocumentTest {
 
+    protected static final RestDocsResponse ERROR_RESPONSE = new RestDocsResponse()
+            .responseBodyField(
+                    fieldWithPath("errorCode").type(STRING).description("에러 코드"),
+                    fieldWithPath("message").type(STRING).description("에러 메시지")
+            );
+    private static final String MOCKED_ACCESS_TOKEN = "access-token";
+    private static final String MOCKED_REFRESH_TOKEN = "refresh-token";
+
     @MockitoBean
     protected AuthService authService;
     @MockitoBean
     protected MemberService memberService;
     @MockitoBean
     protected StoreService storeService;
-
-    @Autowired
-    private JwtManager jwtManager;
+    @MockitoBean
+    protected JwtManager jwtManager;
     @LocalServerPort
     private int port;
 
@@ -48,6 +59,14 @@ void setEnvironment(RestDocumentationContextProvider restDocumentation) {
                 .build();
     }
 
+    @BeforeEach
+    void mockingJwtManager() {
+        doReturn(MOCKED_ACCESS_TOKEN).when(jwtManager).issueAccessToken(1L);
+        doReturn(MOCKED_REFRESH_TOKEN).when(jwtManager).issueRefreshToken(1L);
+        doReturn(1L).when(jwtManager).resolveAccessToken(MOCKED_ACCESS_TOKEN);
+        doReturn(1L).when(jwtManager).resolveRefreshToken(MOCKED_REFRESH_TOKEN);
+    }
+
     protected final RestDocsRequest request() {
         return new RestDocsRequest();
     }
@@ -60,16 +79,20 @@ protected final RestDocsFilterBuilder document(String identifierPrefix, int stat
         return new RestDocsFilterBuilder(identifierPrefix, Integer.toString(statusCode));
     }
 
+    protected final RestDocsFilterBuilder document(String identifierPrefix, BusinessErrorCode errorCode) {
+        return new RestDocsFilterBuilder(identifierPrefix, errorCode.name());
+    }
+
     protected final RequestSpecification given(RestDocumentationFilter documentationFilter) {
         return RestAssured.given(spec)
                 .filter(documentationFilter);
     }
 
     protected final String accessToken() {
-        return jwtManager.issueAccessToken(1L);
+        return MOCKED_ACCESS_TOKEN;
     }
 
     protected final String refreshToken() {
-        return jwtManager.issueRefreshToken(1L);
+        return MOCKED_REFRESH_TOKEN;
     }
 }
diff --git a/src/test/java/eatda/document/auth/AuthDocumentTest.java b/src/test/java/eatda/document/auth/AuthDocumentTest.java
@@ -2,6 +2,7 @@
 
 import static org.mockito.ArgumentMatchers.anyString;
 import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.doThrow;
 import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
 import static org.springframework.restdocs.payload.JsonFieldType.BOOLEAN;
 import static org.springframework.restdocs.payload.JsonFieldType.NUMBER;
@@ -16,11 +17,15 @@
 import eatda.document.RestDocsRequest;
 import eatda.document.RestDocsResponse;
 import eatda.document.Tag;
+import eatda.exception.BusinessErrorCode;
+import eatda.exception.BusinessException;
 import io.restassured.http.ContentType;
 import java.net.URI;
 import java.net.URISyntaxException;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.HttpHeaders;
 
@@ -45,7 +50,7 @@ class RedirectOauthLoginPage {
                 );
 
         @Test
-        void Oauth_로그인_페이지로_리다이렉트_할_수_있다() throws URISyntaxException {
+        void Oauth_로그인_페이지_리다이렉트_성공() throws URISyntaxException {
             doReturn(new URI("http://localhost:8080")).when(authService).getOauthLoginUrl(anyString());
 
             var document = document("auth/oauth-redirect", 302)
@@ -61,6 +66,22 @@ class RedirectOauthLoginPage {
                     .then()
                     .statusCode(302);
         }
+
+        @EnumSource(value = BusinessErrorCode.class, names = {"UNAUTHORIZED_ORIGIN"})
+        @ParameterizedTest
+        void Oauth_로그인_페이지_리다이렉트_실패(BusinessErrorCode errorCode) {
+            doThrow(new BusinessException(errorCode)).when(authService).getOauthLoginUrl(anyString());
+
+            var document = document("auth/oauth-redirect", errorCode)
+                    .request(requestDocument)
+                    .response(ERROR_RESPONSE)
+                    .build();
+
+            given(document)
+                    .header(HttpHeaders.REFERER, origin)
+                    .when().get("/api/auth/login/oauth")
+                    .then().statusCode(errorCode.getStatus().value());
+        }
     }
 
     @Nested
@@ -105,6 +126,24 @@ class Login {
                     .when().post("/api/auth/login")
                     .then().statusCode(201);
         }
+
+        @EnumSource(value = BusinessErrorCode.class, names = {"UNAUTHORIZED_ORIGIN", "OAUTH_SERVER_ERROR"})
+        @ParameterizedTest
+        void 로그인_실패(BusinessErrorCode errorCode) {
+            LoginRequest request = new LoginRequest("code", "http://localhost:3000");
+            doThrow(new BusinessException(errorCode)).when(authService).login(request);
+
+            var document = document("auth/login", errorCode)
+                    .request(requestDocument)
+                    .response(ERROR_RESPONSE)
+                    .build();
+
+            given(document)
+                    .contentType(ContentType.JSON)
+                    .body(request)
+                    .when().post("/api/auth/login")
+                    .then().statusCode(errorCode.getStatus().value());
+        }
     }
 
     @Nested
@@ -138,5 +177,23 @@ class ReissueToken {
                     .when().post("/api/auth/reissue")
                     .then().statusCode(201);
         }
+
+        @EnumSource(value = BusinessErrorCode.class, names = {"EXPIRED_TOKEN", "UNAUTHORIZED_MEMBER"})
+        @ParameterizedTest
+        void 토큰_재발급_실패(BusinessErrorCode errorCode) {
+            ReissueRequest request = new ReissueRequest(refreshToken());
+            doThrow(new BusinessException(errorCode)).when(jwtManager).resolveRefreshToken(request.refreshToken());
+
+            var document = document("auth/reissue", errorCode)
+                    .request(requestDocument)
+                    .response(ERROR_RESPONSE)
+                    .build();
+
+            given(document)
+                    .contentType(ContentType.JSON)
+                    .body(request)
+                    .when().post("/api/auth/reissue")
+                    .then().statusCode(errorCode.getStatus().value());
+        }
     }
 }
diff --git a/src/test/java/eatda/document/member/MemberDocumentTest.java b/src/test/java/eatda/document/member/MemberDocumentTest.java
@@ -5,6 +5,7 @@
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.doNothing;
 import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.doThrow;
 import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
 import static org.springframework.restdocs.payload.JsonFieldType.BOOLEAN;
 import static org.springframework.restdocs.payload.JsonFieldType.NUMBER;
@@ -18,9 +19,13 @@
 import eatda.document.RestDocsRequest;
 import eatda.document.RestDocsResponse;
 import eatda.document.Tag;
+import eatda.exception.BusinessErrorCode;
+import eatda.exception.BusinessException;
 import io.restassured.http.ContentType;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
 import org.springframework.http.HttpHeaders;
 
 public class MemberDocumentTest extends BaseDocumentTest {
@@ -38,7 +43,7 @@ class CheckNickname {
                 );
 
         @Test
-        void 중복되지_않는_닉네임을_확인할_수_있다() {
+        void 중복_닉네임_확인_성공() {
             doNothing().when(memberService).validateNickname(anyString(), anyLong());
 
             var document = document("member/nickname-check", 204)
@@ -52,6 +57,26 @@ class CheckNickname {
                     .when().get("/api/member/nickname/check")
                     .then().statusCode(204);
         }
+
+        @EnumSource(value = BusinessErrorCode.class,
+                names = {"UNAUTHORIZED_MEMBER", "EXPIRED_TOKEN", "DUPLICATE_NICKNAME"})
+        @ParameterizedTest
+        void 중복_닉네임_확인_실패(BusinessErrorCode errorCode) {
+            doThrow(new BusinessException(errorCode))
+                    .when(memberService).validateNickname(anyString(), anyLong());
+
+            var document = document("member/nickname-check", errorCode)
+                    .request(requestDocument)
+                    .response(ERROR_RESPONSE)
+                    .build();
+
+            given(document)
+                    .contentType(ContentType.JSON)
+                    .header(HttpHeaders.AUTHORIZATION, accessToken())
+                    .queryParam("nickname", "existing-nickname")
+                    .when().get("/api/member/nickname/check")
+                    .then().statusCode(errorCode.getStatus().value());
+        }
     }
 
     @Nested
@@ -67,7 +92,7 @@ class CheckPhoneNumber {
                 );
 
         @Test
-        void 중복되지_않는_전화번호를_확인할_수_있다() {
+        void 중복_전화번호_확인_성공() {
             doNothing().when(memberService).validatePhoneNumber(anyString(), anyLong());
 
             var document = document("member/phone-number-check", 204)
@@ -81,6 +106,26 @@ class CheckPhoneNumber {
                     .when().get("/api/member/phone-number/check")
                     .then().statusCode(204);
         }
+
+        @EnumSource(value = BusinessErrorCode.class,
+                names = {"UNAUTHORIZED_MEMBER", "EXPIRED_TOKEN", "DUPLICATE_PHONE_NUMBER"})
+        @ParameterizedTest
+        void 중복_전화번호_확인_실패(BusinessErrorCode errorCode) {
+            doThrow(new BusinessException(errorCode))
+                    .when(memberService).validatePhoneNumber(anyString(), anyLong());
+
+            var document = document("member/phone-number-check", errorCode)
+                    .request(requestDocument)
+                    .response(ERROR_RESPONSE)
+                    .build();
+
+            given(document)
+                    .contentType(ContentType.JSON)
+                    .header(HttpHeaders.AUTHORIZATION, accessToken())
+                    .queryParam("phoneNumber", "01012345678")
+                    .when().get("/api/member/phone-number/check")
+                    .then().statusCode(errorCode.getStatus().value());
+        }
     }
 
     @Nested
@@ -126,5 +171,26 @@ class UpdateMember {
                     .when().put("/api/member")
                     .then().statusCode(200);
         }
+
+        @EnumSource(value = BusinessErrorCode.class,
+                names = {"UNAUTHORIZED_MEMBER", "EXPIRED_TOKEN", "DUPLICATE_NICKNAME", "DUPLICATE_PHONE_NUMBER",
+                        "INVALID_MOBILE_PHONE_NUMBER", "INVALID_MARKETING_CONSENT"})
+        @ParameterizedTest
+        void 회원_정보_수정_실패(BusinessErrorCode errorCode) {
+            MemberUpdateRequest request = new MemberUpdateRequest("update-nickname", "01012345678", "성북구", true);
+            doThrow(new BusinessException(errorCode)).when(memberService).update(anyLong(), eq(request));
+
+            var document = document("member/update", errorCode)
+                    .request(requestDocument)
+                    .response(ERROR_RESPONSE)
+                    .build();
+
+            given(document)
+                    .contentType(ContentType.JSON)
+                    .header(HttpHeaders.AUTHORIZATION, accessToken())
+                    .body(request)
+                    .when().put("/api/member")
+                    .then().statusCode(errorCode.getStatus().value());
+        }
     }
 }
diff --git a/src/test/java/eatda/document/store/StoreDocumentTest.java b/src/test/java/eatda/document/store/StoreDocumentTest.java
@@ -3,6 +3,7 @@
 
 import static org.mockito.ArgumentMatchers.anyString;
 import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.doThrow;
 import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
 import static org.springframework.restdocs.payload.JsonFieldType.ARRAY;
 import static org.springframework.restdocs.payload.JsonFieldType.STRING;
@@ -15,10 +16,14 @@
 import eatda.document.RestDocsRequest;
 import eatda.document.RestDocsResponse;
 import eatda.document.Tag;
+import eatda.exception.BusinessErrorCode;
+import eatda.exception.BusinessException;
 import io.restassured.http.ContentType;
 import java.util.List;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
 import org.springframework.http.HttpHeaders;
 
 public class StoreDocumentTest extends BaseDocumentTest {
@@ -44,7 +49,7 @@ class SearchStores {
                 );
 
         @Test
-        void 음식점_검색_결과를_반환한다() {
+        void 음식점_검색_성공() {
             String query = "농민백암순대";
             StoreSearchResponses responses = new StoreSearchResponses(List.of(
                     new StoreSearchResponse("17163273", "농민백암순대 본점", "서울 강남구 대치동 896-33"),
@@ -64,5 +69,25 @@ class SearchStores {
                     .when().get("/api/shop/search")
                     .then().statusCode(200);
         }
+
+        @EnumSource(value = BusinessErrorCode.class,
+                names = {"UNAUTHORIZED_MEMBER", "EXPIRED_TOKEN", "MAP_SERVER_ERROR"})
+        @ParameterizedTest
+        void 음식점_검색_실패(BusinessErrorCode errorCode) {
+            String query = "농민백암순대";
+            doThrow(new BusinessException(errorCode)).when(storeService).searchStores(anyString());
+
+            var document = document("store/search", errorCode)
+                    .request(requestDocument)
+                    .response(ERROR_RESPONSE)
+                    .build();
+
+            given(document)
+                    .contentType(ContentType.JSON)
+                    .header(HttpHeaders.AUTHORIZATION, accessToken())
+                    .queryParam("query", query)
+                    .when().get("/api/shop/search")
+                    .then().statusCode(errorCode.getStatus().value());
+        }
     }
 }
