## Spring Rest Docs 가 생성해주는 snippets
Spring REST Docs는 테스트가 성공하면 `build/generated-snippets/{operation-name}/` 경로에 여러 개의 `.adoc` 파일(Snippet)을 자동으로 생성합니다.
기본적으로 생성되는 것과 추가 설정을 통해 생성되는 목록을 정리해 드릴게요.
---
### 1. 기본 생성 스니펫 (별도 설정 없이 생성)
테스트를 실행하면 무조건 만들어지는 가장 기초적인 조각들입니다.
| **파일명** | **내용** | **용도** |
| --- | --- | --- |
| **`http-request.adoc`** | HTTP 요청 전문 | 메서드, URL, 헤더, 바디를 모두 포함 |
| **`http-response.adoc`** | HTTP 응답 전문 | 상태 코드, 응답 헤더, 응답 바디 포함 |
| **`curl-request.adoc`** | cURL 명령어 | 터미널에서 바로 복사해서 테스트할 수 있는 형태 |
| **`httpie-request.adoc`** | HTTPie 명령어 | HTTPie 도구용 요청 명령어 |
| **`request-body.adoc`** | 요청 페이로드(Body) | 요청 본문 데이터만 별도로 추출 |
| **`response-body.adoc`** | 응답 페이로드(Body) | 응답 본문 데이터만 별도로 추출 |
---
### 2. 정의가 필요한 스니펫 (테스트 코드에 명시해야 생성)
이 파일들은 `document()` 메서드 안에 `requestFields`, `responseFields` 등을 직접 선언해야만 생성됩니다. 사용자님이 지금 씨름하고 계신 바로 그 부분들입니다.
| **파일명** | **연관 메서드** | **설명** |
| --- | --- | --- |
| **`request-fields.adoc`** | `requestFields()` | 요청 JSON의 각 필드명, 타입, 설명 |
| **`response-fields.adoc`** | `responseFields()` | 응답 JSON의 각 필드명, 타입, 설명 |
| **`path-parameters.adoc`** | `pathParameters()` | `/api/users/{id}`에서 `{id}`에 대한 설명 |
| **`query-parameters.adoc`** | `queryParameters()` | `?page=1&size=10` 같은 쿼리 스트링 설명 |
| **`request-parts.adoc`** | `requestParts()` | 파일 업로드 시 `MultiPartFile` 등에 대한 설명 |
| **`request-part-fields.adoc`** | `requestPartFields()` | 특정 Part 내부의 JSON 필드 설명 |
| **`request-headers.adoc`** | `requestHeaders()` | 인증 토큰 등 커스텀 헤더에 대한 설명 |
| **`response-headers.adoc`** | `responseHeaders()` | 응답 시 내려주는 커스텀 헤더 설명 |
---
### 3. 기타 특수 스니펫
- **`links.adoc`**: 하이퍼미디어(HATEOAS) 링크 구조를 문서화할 때 (`links()`) 생성됩니다.
- **`custom-snippet.adoc`**: 사용자가 직접 만든 템플릿을 통해 생성할 수도 있습니다.
---
### 💡 팁: 왜 내 폴더에는 몇 개 없지?
지금 사용자님의 상황처럼 **"아무렇게나 설정하면 에러가 나는"** 이유는, REST Docs가 **"너 이 필드 문서화하기로 했으면 하나도 빠짐없이 다 적어! 안 그러면 파일(`-fields.adoc`) 안 만들어줄 거야!"**라고 버티기 때문입니다.
1. **에러를 해결하고 테스트가 통과**해야 해당 `.adoc` 파일이 폴더에 나타납니다.
2. 에러가 너무 짜증 난다면 `relaxedResponseFields`를 써서 일단 통과시킨 후, 생성된 파일을 확인해 보세요.
댓글
댓글 쓰기