< 💡 Spring Rest Docs 로 Swagger API 문서 관리 자동화 > 💬 Spring Rest Docs 란? Spring REST Docs 는 RESTful 서비스의 문서화를 도와주는 도구이다. 문서 작성 도구로 Asciidoctor 를 기본적으로 사용하며, 이것을 통해 HTML 문서를 생성한다. 필요한 경우 Markdown 문법을 사용하도록 변경할 수 있다. RESTful API를 문서화 할때 중요한 포인트는 API 에서 필요한 HTTP 요청과 응답의 리소스를 설명하는 것인데 Spring REST Docs 를 사용할 경우 테스트 코드를 작성하여 이러한 리소스와 HTTP 요청/응답에 대한 세부 내용을 문서화하는데 편리한 기능을 제공한다. 💬 Swagger 란? RESTful API 를 약속된 규칙에 따라 json 이나 yaml 형식으로 문서화한 Open API Specification(OAS) 라는게 있는데 이 문서를 관리하기위한 목적으로 만들어진 프레임워크다. API 문서 자동화 도구로 Spring REST Docs 의 비교군으로 자주 등장하는데 Spring 을 사용할 경우 서비스 코드에 어노테이션만 추가하면 멋진 API 문서 하나가 뚝딱 만들어지는 신기한 도구다. 게다가 실제로 API 를 요청해 볼 수 있는 기능도있기 때문에 API 를 어떻게 요청하고 어떤 응답을 내려주는지도 테스트가 가능하다. 💬 이걸 하게 된 이유? - wiki 페이지를 통해 개발한 API 문서를 정리하고 타 부서에 공유하였는데 변경사항이 발생할때마다 관리가 힘들고 잘못 작성되거나 변경사항이 반영되지 않아 커뮤니케이션 비용이 많이 발생하였다. - Swagger 를 통해 API 문서를 제공해보니 API 에 대한 테스트도 할 수 있고 코드가 변경될때 같이 변경할 수 있는 장점이 있으나 실제 코드에 API 문서를 작성하기 위한 코드를 같이 작성해야했고 검증되지 않은(정상작동하지 않는) API 가 노출될 수 있었다. - Spring Rest Docs 를 써보니 테스트 코드를 통해 API 문서를 작성할 수 있어 검증된 API 만 문서를 만들수 있고 실제 코드는 API 문서에 관련된 코드를 작성하지 않아서 좋았지만 Swagger 에서 제공해주는 API 호출 기능이 없어서 아쉬웠다.(개인적인 생각이지만 UI 도 Swagger 가 더 좋다고 느꼈다) - 좀 더 좋은 방법이 없을까를 찾던 중 링크로 걸어둔 내용을 보게 되었고 팀 프로젝트 상황에 맞게 커스터마이징 하여 적용해 보았다. 💬 좋았던 점 - 테스트 코드를 통해 어느정도 검증된 API 가 문서에 반영될 수 있다는 점(+ 이를 Swagger 로 실행해 볼 수 있다는 점). - API에 변경이 발생하면 자연스럽게 테스트 코드도 변경이 필요하게되고 이로 인해 API 문서 변경도 자연스럽게 발생한다는 점.(단, API 문서까지 자연스럽게 변경되려면 빌드/배포 구조까지 잘 잡혀져야 한다) - Swagger 특성상 여러 API 문서들을 같이 관리할 수 있어 통합 API 문서를 구축할 수 있다. 이를 통해 각 컴포넌트 별로 Swagger URL 이 따로 있지 않아도 되어 타 부서에 공유할 때 편했다.(wiki 로 치면 API 문서 부모 페이지 하나만 공유하면 되는것과 동일) 💬 아쉬운 점 - Spring Rest Docs 를 쓰기 때문에 어쩔수 없는 한계인가 싶긴 하지만 테스트 코드 작성시 API 문서를 작성하기 위한 테스트 코드를 추가로 작성해야 한다. - 여러가지 검증을 위한 테스트 코드를 작성하다보면 API 문서에 영향을 줄 수 있기 때문에 이에 대한 고려를 하면서 테스트 코드를 작성해야 한다.(가끔은 주객전도가 된듯한 느낌도 받는다) - 가끔씩 타 부서에서 미리 코드를 작성할 수 있게 API Interface 공유가 불가능하냐는 문의가 들어오면 답이 없다.(이럴땐 어쩔수 없이 우리쪽 API 설계 문서를 공유해주곤 한다) 📚 Reference - Swagger: https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/ - Spring Rest Docs: https://docs.spring.io/spring-restdocs/docs/current/reference/html5/ - Rest Docs API specification Integration: https://github.com/ePages-de/restdocs-api-spec - Restdocs Spec Generation Support: https://github.com/BerkleyTechnologyServices/restdocs-spec