[Spring] RestDocs와 Swagger

프론트와 같이 협업을 하면서 API문서를 제공해야 하는 상황이 왔다.

처음에는 Notion에 하나하나 작성하였으나 API가 수정되었을때 변경하지 않아 불일치 되는 경우가 생기게 되었다.

이러한 문제를 해결하기 위해 문서 자동화를 도입하게 되었다.

Spring에서 유명한 Swagger와 RestDocs중 어떤것을 도입할지 고민하기 위해 찾아보았다.

 

	Spring Rest Docs	Swagger
장점	제품코드에 영향 없다.	API 를 테스트 해 볼수 있는 화면을 제공한다.
	테스트가 성공해야 문서작성된다.	적용하기 쉽다.
단점	적용하기 어렵다.	제품코드에 어노테이션 추가해야한다.
		제품코드와 동기화가 안될수 있다.

 

Swagger는 적용하기 쉽지만 컨트롤러에 어노테이션을 추가해야 하며 실제로 동작을 하지 않을 수도 있다.

또한 백엔드 테스트 환경에 더 적합하다.

RestDocs의 경우는 코드를 따로 건들지 않고 테스트 코드에 작성한 값과 결과가 문서화되어 나오게 된다.

단점은 적용하기 어렵다는 점이다.

 

우리는 프론트에 제공해야 하는 입장에서 예시까지 있으면 더 좋기때문에 RestDocs를 적용하기로 했다.

 

발생한 문제점 및 불편한점

1. RestDocs 공식문서가 예전 버전을 기준으로 작성이 되어있어서 공식문서대로 작성을 해도 되지않는 문제가 발생했다.
2. 한번의 빌드만으로 jar에 문서가 포함되지 않는 이슈가 발생했다.(해결 실패)
3. asciiDoc을 이용하여 문서를 설정해야 하는 어려움이 있다.
4. html로 변환하기 위해 adoc파일을 하나하나 만들어 줘야한다.

RestDocs를 적용하기 위해 블로그를 참조하며 진행한 결과 2일에 걸쳐 연동할 수 있었다.

 

RestDocs를 모두 적용하고 나서 만족했지만 적용이 왜 힘든지 알게되었다.

출처 : https://techblog.woowahan.com/2597/