## Spring REST Docs에서 **Exception(비즈니스 예외 및 에러 응답)**을 문서화하는 가장 현실적인 방법 2가지
### 1. 테스트 코드에서 "실패 케이스" 직접 문서화 (가장 추천)
성공 케이스만 테스트하는 것이 아니라, **의도적으로 예외를 발생시키는 테스트**를 짜고 그 응답을 스니펫으로 뽑는 방식입니다.
```java
`@Test
@DisplayName("파일 업로드 실패: 허용되지 않은 확장자")
void uploadFailInvalidExtension() {
// Given: 잘못된 파일 준비
var badFile = new MockMultipartFile("files", "test.exe", "application/octet-stream", "bad".getBytes());
// When
var result = mvc.post().uri("/api/attachFile/upload").multipart().file(badFile).exchange();
// Then & Document
result.assertThat()
.apply(document("upload-fail-invalid-extension", // 실패 케이스용 별도 폴더
responseFields(
fieldWithPath("code").description("에러 코드 (예: INVALID_EXTENSION)"),
fieldWithPath("message").description("에러 상세 사유"),
fieldWithPath("data").description("추가 에러 정보 (null)").optional()
)
))
.hasStatusBadRequest(); // 400 에러 검증
}`
```
- **장점:** 실제 해당 에러가 났을 때의 **HTTP 응답 본문(JSON)**을 그대로 문서에 박아넣을 수 있습니다. 프론트엔드 개발자가 가장 좋아하는 방식입니다.
- **단점:** 에러 케이스가 많을수록 테스트 코드가 늘어납니다.
---
### 2. "공통 에러 코드" 표(Table) 만들기
모든 API에 공통으로 적용되는 에러(예: 401 Unauthorized, 500 Internal Error)는 개별 API 문서에 넣기보다 **공통 섹션**에 표로 정리하는 것이 효율적입니다.
이것을 자동화하고 싶다면 **별도의 테스트 클래스**를 만들어 모든 Enum(ErrorCode)을 스니펫으로 뽑아낼 수 있습니다.
### [Step 1] 에러 코드를 뽑아내는 커스텀 테스트 작성
```java
@Test
void errorCodes() throws Exception {
// 우리 프로젝트의 ErrorCode Enum을 Map으로 변환하여 문서화하는 로직
// (보통 컨트롤러에서 ErrorCode를 반환하는 임시 엔드포인트를 만들어 테스트합니다)
this.mockMvc.perform(get("/api/common/error-codes"))
.andDo(document("common-error-codes",
snippets -> {
// 커스텀 스니펫 생성 로직...
}
));
}`
```
### [Step 2] index.adoc에 공통 섹션 추가
AsciiDoc
```java
`[[Common-Errors]]
== 공통 에러 코드
[cols="2,3,5"]
|===
| 코드 | 메시지 | 설명
| `INVALID_INPUT`
| 잘못된 입력값입니다.
| 요청 파라미터가 누락되었거나 형식이 틀린 경우
| `FILE_TOO_LARGE`
| 파일 크기가 제한을 초과했습니다.
| 단일 파일 10MB, 총합 50MB 초과 시 발생
|===`
```
---
### 3. 더 전문적인 방법: `Custom Snippet` 활용
만약 `ErrorCode`라는 Enum 객체를 가지고 계신다면, 이를 순회하며 자동으로 `.adoc` 테이블 파일을 생성하는 **커스텀 스니펫 클래스**를 만들 수 있습니다. (이 방법은 코드가 조금 길지만, 한 번 짜두면 ErrorCode에 새 값을 추가할 때마다 문서가 자동으로 갱신됩니다.)
---
### 💡 지금 바로 적용하기 좋은 팁
지금 당장은 **"주요 예외 케이스(실패 테스트)"**를 하나 만드셔서 `document("upload-fail-...")`로 응답 조각을 뽑아보세요.
사용자님 프로젝트의 **`ErrorCode` 체계**(Enum 형태인지, 단순히 String인지)를 알려주시면, 그걸 표로 자동 변환하는 구체적인 코드 예시를 짜드릴 수 있습니다.
**어떤 방식이 더 끌리시나요?**
1. 실제 에러 응답 JSON을 보여주는 **실패 테스트 방식**?
2. 전체 에러 리스트를 한눈에 보여주는 **공통 표 방식**?
댓글
댓글 쓰기