[Spring Rest Docs] Enum, 예외 코드 문서화를 위한 Custom Snippet 생성(AbstractFieldsSnippet)

 

Spring Rest Docs에서 Error Code나 Enum의 문서를 보여주기 위해서는 Custom Snippet을 사용하는 것이 좋다.

기본 템플릿도 수정해서 사용할 수 있는데 일반적으로 optional, default, constraints 같은 column을 추가해서 사용한다. 

 

 

Error Code나 Enum을 나타내기 위한 템플릿은 column이 아예 달라서 새로 추가하는 것이 좋다. restdocs-core의 default snippet 템플릿이 있는 경로대로 테스트의 resources 하위에 test/resources/org/.. 디렉토리를 생성하고 템플릿을 추가하면 된다.

 

 

 

나는 error code를 문서화하기 위해 errorcde-response-fields.snippet을 생성했는데  xxx-response-fields처럼 네이밍을 지키면서 추가하면 된다. 그 다음 Custom Snippet을 적용하기 위해 AbstractFieldsSnippet를 상속받는 클래스를 구현한다.

 

 

추상 메서드인 getContentType(), getContent()를 구현해줘야 하는데 실수로 그냥 지나쳤다가 문서가 제대로 생성 되지 않았다.

getContent()로 body를 꺼내서 veriftContent()를 할 때 length가 0이면 SnippetException body is empty 예외가 발생한다. ㅠㅠ

 

 

그래서 아래와 같이 수정을 해주었다.

 

 

이제 custom snippet, CustomResponseFieldSnippet 클래스를 추가했으면 test 디렉토리 내부에 Enum 값들을 반환해 주는 Controller를 생성하고 해당 Controller에서 문서화하려는 Enum 값들을 반환해 준다

아래와 같이 Rest Docs용으로 생성한 Controller에 요청을 보내면 Enum 값들을 Map으로 반환해 줘서 key는 문서의 row로 사용하고 value는 column으로 사용한다. (column에서 보여줄 status, code, message 등을 DTO로 생성한다,)

 

그러면 아래와 같이 response가 생성이 되는데 key를 fieldWithPath()의 path로 지정하고 type, code, status, message는 attributes에 값을 넣어주면 column으로 보여줄 수 있다.

 

 

기존에는 responseFIelds(fieldWithPath()...)의 형태로 추가를 하면 response-fields.snippet을 찾아서 문서가 생성이 되었다.

 

하지만 이번에는 custom으로 생성을 하기 때문에 아까 생성해 놓은 CustomResponseFieldSnippet의 생성자를 사용해야 한다.

ignoreUndocumentedFields를 true로 줘서 문서화하지 않은 필드는 무시하도록 한다.

 

 

이제 Rest Docs 테스트 코드를 작성하면 되는데 나는 document()의 공통 부분을 restDocsTemplate() 메서드로 빼두었다.

 

createErrorCodeFieldDescriptors()에서 Map<String, ErrorCodeResponse>를 받아서 FieldDescriptor를 생성한다.

 

path에는 Map의 key가 들어가고

attributes에는 Map의 value인 ErrorCodeResponse의 type, code, status, message 필드들을 추가해 주면 된다.

 

 

이렇게 하면 Error Code를 테이블 형태로 보여줄 수 있다. ErrorCode를 하나의 Enum 클래스에서 관리한다면 자동으로 Error Code 동기화가 돼서 좋은 것 같다!

 

 

 

 

[참고]

RestDocs - Custom Error Code Enum 문서화

Spring Rest Docs 적용 | 우아한형제들 기술블로그

Spring REST Docs 적용 및 최적화 하기