Spring REST Docs

 

 

Spring Rest Docs를 이용하여 API 스펙을 명시하는데 필요한 기본 설정을 하였다.

 

https://github.com/Lemon-soju/Vue_Spring/commit/1b0be0f04b6b4b74a5eb05d2e4d1afa89c608a49

Merge pull request #14 from Lemon-soju/slave-01 · Lemon-soju/Vue_Spring@1b0be0f

 

 

 

 

 

Spring Rest Docs란?

 

 

• API문서 작성을 자동화해주는 도구는 여러가지가 있지만 대표주자로 Swagger와 Spring Rest Docs가 있다.
• Swagger는 API 동작을 테스트하는 용도에 더 특화되어있다. 문서 상에도 실제로 API call이 가능하다.
• 반면 Spring REST Docs는 성공하는 Test Case를 기반으로 API 스펙을 작성하기 때문에 프로덕션 코드를 건드릴 필요가 없고, 작성되는 문서의 가독성도 상당히 좋은 편이다.

 

요약하면 Spring Rest Docs는 테스트 코드를 기반으로 자동으로 API 문서를 작성할 수 있게 도와주는 프레임워크이다. 그렇기 때문에 반드시 Test가 통과되어야 문서가 작성 된다는 장점이 있다.

 

Test 통과가 전제조건이기 때문에 API 스펙이 변경되거나 추가/삭제 되는 부분에 대해 항상 테스트 코드를 수정해야되고, API 문서가 최신화 될 수 있도록 해준다.

 

 

API 스펙 설계

API 스펙 설계 과정이 필요한 이유는 다음과 같다.

 

• 개발에 착수하기 전에 구조에 대해 고민할 시간이 생긴다.
• API 스펙을 프론트엔드에게 전달할 때는 문서로 정리해야 한다.
• 실제로 로직을 작성하기 전에 스펙을 리뷰하는 단계가 생기고, 아직 코드를 작성하지 않았으니 변경 사항을 빠르게 반영할 수 있다.
• 문서를 착실하게 작성해 두면, 커뮤니케이션으로 낭비하는 시간이 줄어든다.