들어가기 전
최근 프로젝트를 진행하면서, API 명세에 대한 이야기를 많이 나누었다. API가 점점 늘어나고, 프론트와의 협업이 다가오면서 점점 API 문서화의 필요성을 실감하게 된다.
API를 사용하는 곳은 정말 많다. 로컬 환경 뿐만 아니라 개발(dev), 운영(prod) 환경에서 API 요청이 잘 되는지 확인을 해야할 때도 있다. 또한 API의 스펙자체를 문서화 해놓지 않는다면, 프론트엔드 개발자와의 협업이 정말 힘들어질 것이다.
이번 글에서는 현재 진행중인 프로젝트에서 어느 부분을 고려해서 어떤 API를 어떻게 문서화, 테스트했는지 소개하겠다. 나름 개발 좀 해봤다 하면 들어봤을 만한 툴들을 기준으로 많이 알아보자.
이 글은 어떤 API 문서와 테스트 툴을 사용할지에 대한 고민이 담긴 글이기 때문에 자세한 사용 방법에 대해선 기술하지 않는다.
Swagger
장점
문서에서 API를 직접 테스트 해 볼 수 있다.
API 문서와 테스트 툴을 따로 두지 않아도 되는 것은 Swagger만의 큰 장점이라고 생각한다. 버튼 한 두번 누르는 것으로 API를 직접 실행해 볼 수 있다는 것은 정말 메리트 있다.
간편한 설정
아래와 같이 간단하게 의존성만 추가해주면 별도의 설정 없이 손쉽게 사용할 수 있다.
단점
문서를 위한 코드 작성
Swagger의 단점은 정말 명확하다. API 명세를 작성할 뿐인데, 실제 코드레벨에서 부가적인 작업이 필요하다. 불편한 점은 코드를 작성해야 한다는 행위 자체가 아니다.
가장 불편한 점은 컨트롤러 레이어에서 요청(request)과 응답(response) 객체에 Swagger에 관련한 코드가 정말 많이 생긴다. 다 작성하고 나면 실제로 API의 기능을 위해 동작하는 코드보다 더 많아보이기도 할 정도다.
또한 새로운 코드를 작성할 때 마다 매번 Swagger 코드를 추가적으로 작성해야 한다. 이로 인해 코드가 더 길어지고 가독성 또한 떨어진다.
신뢰성
실제로 Swagger로 작성된 잘못된 API 문서를 본 적이 있는가? 잘못된 문서를 기반으로 만들어진 기능을 다시 Fix하는 것은 정말 많은 시간과 자원을 낭비하는 행위라고 생각한다.
API를 보기 편하게, 신뢰성을 높이기 위해 API 문서를 작성하는데 이게 왜 단점으로 적용되는지 아이러니하게 느껴질 수 있다. 밑에서 알아보겠지만, 다른 API 문서 툴들은 문서 작성을 해당 라이브러리가 강제하는 편이다.
하지만 Swagger는 API 문서를 개발자가 직접 작성할 수 있기 때문에 오히려 신뢰성일 떨어질 수 있다는 뜻이다.
Spring Rest Docs
장점
테스트 커버리지를 높일 수 있다.
Spring Rest Docs는 API 문서화를 위해 API에 대한 테스트를 작성해야 한다. 한 마디로 문서화를 위해선 테스트 코드를 작성할 줄 알아야 하고 작성해야만 한다는 것이다.
말만 들으면 단점이라고 생각될 수 있다. 하지만, 이는 Swagger가 API의 문서화를 위해 애플리케이션 코드 레벨에 Swagger 코드를 작성해야 하는 것과는 사뭇 다른 느낌이다.
Swagger를 사용하므로써 작성해야 하는 코드는 Swagger 라이브러리에 의존한다. 또한 실제 애플리케이션이 동작하는 코드에 + 알파를 해야한다는 점도 있다.
반면, Spring Rest Docs가 요구하는 코드는 외부 라이브러리에 의존하지도 않고 실제 애플리케이션 코드에 작업을 해야하는 것도 아니다. 오히려 테스트 코드를 작성함으로써 애플리케이션과 API 문서에 대한 신뢰성을 높일 수 있다.
AsciiDoc 또는 Markdown으로 작성 가능
테스트 코드를 작성하다 보면 테스트 코드만으로 작성하기 어려운 부분이 생기는데 해당 부분들은, AsciiDoc과 마크다운 문법으로 대체할 수 있다.
단점
꽤나 귀찮은 설정
Spring Rest Docs는 build시 .html 파일을 만들어 사용해서 관련 설정이 필요하기 때문에, Swagger처럼 gradle에 한 두줄 추가하는 것 만으로는 Spring Rest Docs를 제대로 사용할 수 없다.
API 테스트를 위한 .http 도입기
장점
IDE 기능 사용 가능
IntelliJ에서 파일을 작성하기 때문에 IDE에서 제공하는 기능들을 사용할 수 있다.
- Code Highlighting
- 자동 완성
- .json 파일 지원
- ...
깃으로 관리하는 API 테스트 문서
장점들 중에서도 가장 큰 임팩트가 있다. 모든 API 테스트에 대해서 문서로 작성하기 때문에 당연하게도 깃의 관리대상이 된다. 또한 env 파일과 관련한 부분들도 .gitignore로 처리할 수 있다.
다른 개발자가 만든 API 테스트 문서여도 누구나 공용으로 사용할 수 있고, 누가 삭제하더라도 해당 부분을 롤백해서 되살릴 수 있다. 또한 깃은 팀원과 파일을 공유하면서 무료로 사용할 수 있다는 장점도 있다.(포스트 맨과 같은 툴들은 팀 요금제)
단점
다른 툴들에 비해 약간 높은 러닝 커브
유일한 단점이라고 생각된다. 개발자가 값만 넣는게 아니라 코드를 작성해서 API 테스트 문서를 처음부터 끝까지 만들어야 한다. 따라서 .http 파일을 작성하기 위한 학습을 따로 해야한다.
또한 검증 코드를 자바스크립트 코드(?)와 비슷한 언어로 작성해야한다. 필자가 자바스크립트를 써보지 않아서 이게 자바스크립트인지는 잘 모르지만, 확실한건 자바는 아니다.
결론 및 마무리
API 문서화는 각 팀 상황에 맞게 사용하는게 제일 베스트고, 필자가 결정한 툴들은 다음과 같다.
- API 문서화 툴
- Spring Rest Docs : 테스트 커버리지 증가(신뢰도 증가), API 문서 코드로 인한 프로덕션 코드 오염 방지
- API 테스트 툴
- .http(intelliJ) : 깃으로 관리할 수 있다는 큰 장점
