[Spring] API 문서작성 툴 고르기

서론

먼저 실제적인 개발전에 대략적인 준비를 마치고, 먼저 API를 설계해보기로 했다. 또한 설계뿐만 아니라, 프론트엔드 개발자에게 이 정보를 공유해야 하기 때문에 API를 문서화 하여 남겨 간편하게 내가 업데이트한 내용을 문서에서 확인 할 수 있도록 해보기로 했다.

어떤 툴을 사용할까

API를 문서화 하기 위한 여러 툴들이 있어서, 하나씩 알아보며 이번 프로젝트에는 어떤 툴이 적합할지 알아보았다.

Swagger

Swagger API 문서 예시 (링크)

Swagger는 무료로 제공되고, 문서자체에서 바로 해당 API를 테스트해 볼 수 있다는 점이 마음에 들었다. 그러나 API를 카테고리 별로 나누는 기능이 없어서 모든 API가 한페이지에 나타나기 때문에 후에 원하는 API를 한번에 찾을 수 없다는게 단점으로 느껴졌다.

Postman

Postman API 문서 예시 (링크)

Swagger보다 훨씬 문서의 느낌이 나고 UI가 깔끔해서 좋았다. 마크다운 형식으로 간단하게 문서를 작성 가능해서 Swagger보다는 훨씬 원하는 API를 찾기 쉬워서 좋아보였다.

게다가 실제로 날린 API 기반으로 자동으로 문서 부분을 생성해주고, 사용 예시까지 알려주기 때문에, 해당 API에 대한 코멘트만 추가해주면 알아서 자동으로 API 문서를 만들어주었다.

GitBook

GitBook API 문서 예시 (링크)

GitBook은 아주 깔끔한 UI가 장점이었다. Postman이나 Swagger처럼 웹에서 바로 해당 API를 테스트 해보는 기능은 없었지만, 해당 API를 굳이 날려보지 않아도 될 만큼 깔끔한 UI가 있어서 문서로써의 기능을 가장 잘하고 있는 것 같았다.

해당 API에 대한 파라미터와 응답까지 모두 기록하기 편하게 UI가 되어있어서 해당 API에 대한 세부사항 까지를 볼 수 있었다.

하지만 앞서 말했듯이 페이지에서 바로 해당 API에 요청을 날려볼 수는 없는 점이 너무 아쉬웠다.

결론

Swagger는 UI가 너무 맘에 안들기도 하고 직관적이지 않아서 문서의 느낌이 덜한 것 같아 Postman과 GitBook사이에서 고민했는데, Postman보다는 GitBook의 UI가 훨씬 직관적이고 디테일했지만, 온라인에서 바로 테스트 해볼 수 있는 기능이 없다는게 아쉬웠다.

하지만 자세하게 API 문서를 작성해놓으면 굳이 사용자가 해당 API를 테스트해 볼 필요가 있을까라는 생각이 들기도 했고, API 문서라는건 결국 문서이므로 직관적이고 깔끔하게 사용자가 보는것이 중요하다고 생각되서 GitBook으로 결정하기로 했다. Github와 연동이 가능하다는 점도 GitBook의 큰 장점으로 느껴졌다.

그럼 이제 작성 툴도 정했으니, API를 설계해서 문서의 초안을 대략 짜놓고 개발해가며 변경점을 적용해가며 문서와 함께 프로젝트를 시작해볼 것 이다.