API 문서화 도구 선택하기

API 문서화 도구를 찾게 된 계기

9oorp.store version 1을 기획할 때 기획의 중요성을 모르기도 했고 빨리 구현하고 싶었기 때문에 문서화 작업에서 대충 넘긴 것들이 있었다.

그중 하나가 API 문서화였는데 처음에는 밑에처럼 구글 시트에서 URL과 요청방식만 작성했었다.

이렇게 대충 문서로 만드니까 개발기간에 프론트엔드에서 무수한 질물들이 쏟아졌다. (지금 보니 당연하다 ㅋㅋㅋ)

또한 개발하면서 request에 관한 수정사항이 많았는데 이런 수정사항을 한 곳에 작성하지 않고 각자 파편화해서 저장하고 있었기 때문에 중간 회의를 할 때마다 확인 작업이 꼭 필요했다.

문서화가 안 됐을 때 불편함을 몸소 깨닫고 구글 시트 말고 제대로 된 API 문서화를 찾기 위해 내가 도구에 원하는 요구사항과 API 문서화 리스트를 추렸다.

요구사항

첫 번째는 구글 시트보다 API의 자세한 스펙을 적을 수 있어야 한다.

두 번째는 자신이 개발한 API 스펙은 자기가 작성하고 관리해야 한다고 생각했기 때문에 적어도 팀의 백엔드 개발자가 모두 접근해서 수정할 수 있어야 한다.

세 번째는 API 구현 전에 API 문서화를 작성해야 한다. API 스펙을 직접 작성하다 보니 놓치고 있는 부분을 확인할 수 있고 부트캠프에서 프론트엔드 개발도 해보니까 프론트엔드 개발자 입장에서 API 문서화가 정확히 나와 있어야 개발하기 편하고 불필요한 커뮤니케이션을 줄일 수 있다는 걸 느꼈다.

마지막으로 네 번째는 무료여야 한다. 취준생이라 돈이 없다….

API 문서화 도구 리스트

1. Swagger (OpenAPI)
2. spring REST docs
3. gitbook
4. postman

찾아보니까 크게 위 4가지를 사용하는 것 같다. 하나씩 살펴보자.

Swagger (OpenAPI)

Swagger는 2010년에 RESTful API를 설계를 위해 만들어진 오픈 소스로 2015년 SmartBear Software에 인수되면서 OpenAPI로 이름이 변경되었다.

자바 진형에서 spring REST docs와 우선순위를 다툴 정도로 많이 사용하는 도구이며 그래들과 같은 빌드 도구에서 의존성 추가 후 간단한 세팅만 해주면 어노테이션으로 문서로 만들 수 있고 UI 또한 깔끔하다.

오픈 소스이기때문에 무료이고 어노테이션만 추가하면 문서화가 되기 때문에 여러 명의 개발자가 수정할 수 있다.

또한 프로덕션 코드에 문서화 코드도 포함되는데 이는 코드 가독성이 떨어지기 때문에 단점이라고 생각했고 API를 구현한 후 문서로 만들 수 있기 때문에 요구사항 3번을 충족시키지 못해 다른 도구를 선택했다.

spring REST docs

spring REST docs는 spring 프레임워크에서 제공하는 API 문서화 도구이다. Asciidoctor로 작성된 text 문서와 spring test로 생성된 스니펫을 결합해서 문서를 만들 수 있다.

Asciidoctor: AsciiDoc 형식의 텍스트 문서를 HTML5, DocBook, PDF, 등의 다양한 형식으로 변환할 수 있는 프로세서 및 출판 도구

무료이고 swagger처럼 프로젝트 안에서 문서로 만들 수 있기 때문에 여러 개발자와 함께 작성할 수 있다. swagger와 다른 점은 spring REST docs는 테스트 코드에서 설정하기 때문에 프로덕션 코드에 문서화 코드가 포함되지 않는다!

테스트 코드만 작성할 줄 알면 쓰기 좋은 문서화 도구라고 생각은 하지만 테스트 코드가 통과했을 때만 정상적인 문서화가 되기 때문에 API 구현 전에 문서화가 되어야 하는 요구사항을 충족시키지 못했다.

gitbook

gitbook이란 git에서 나온 문서 작성 플랫폼이다. API 문서화뿐만 아니라 Daily planning, Internal Wiki 등 개발자가 작성하면 좋은 템플릿이 갖춰져 있고 노션, Dropbox Paper, Google Docs에서 페이지를 그대로 불러와 사용할 수 있고 슬랙으로 알림을 보내는 등 개발자가 쓰기에 편리한 기능을 많이 제공하고 있다.

테스트를 해보니까 한글은 잘 지원되지 않고 API 스펙이 맞는지 직접 확인하는 수밖에 없지만, 팀원을 초대해서 같이 작업할 수 있고 API 문서화를 API 구현 전에 작성할 수 있는 점, API 스펙을 자세하게 작성할 수 있고 무료(인 줄을 있지…)인 점이 좋아서 프로젝트팀원을 초대해서 열심히 API 문서화를 했다.

gitbook으로 배포하면서 느꼈는데 github와 비슷한 점이 있다.

github처럼 버전관리를 할 수 있어 누군가 실수로 내용을 지웠다면 다시 백업할 수 있고 github의 리파지토리와 연동할 수 있다.

이대로 해결된 줄 알았는데 얼마 후 팀원들에게 gitbook 수정 권한이 없다고 연락이 왔다. 확인해보니 팀원을 초대하는 건 유료 서비스고 일시적으로 혜택을 준 것이다. 이대로 프로젝트가 끝났다면 gitbook에서 끝내면 됐지만 version2에서 요구사항 변경이 많을 거라 판단해서 다른 도구를 찾아보기로 했다.

만약 혼자서 사용할 생각이었다면 gitbook으로 프로젝트를 정리하는 것도 충분히 좋은 선택이라 생각한다.

postman

postman은 개발자들이 설계, 테스트, 문서화, 등등 API 개발을 위한 협업 플랫폼이다. 이전부터 postman이 설치되어 있긴 했지만, API를 테스트하는 용도로만 사용했었는데 찾아보니까 API 문서화, 검색 및 공유 등 API 관련해 많은 서비스를 제공하고 있고 세계 최대의 공개 API 허브를 구성하고 있다고 한다.

postman으로 API 문서화에 대해서 찾아봤더니 내가 원했던 요구사항에 모두 적합했다.

API에 대한 자세한 스펙과 설명을 작성할 수 있고 API를 구현하기 전에 API 문서화를 할 수 있다. 무료 버전은 최대 3명까지, 초대해서 작업할 수 있다.

밑의 사진은 기존 API를 위해 작성했던 테스트를 문서화해본 것이다.

임의의 IP주소로 변경할 수 있고 여러가지 상황에서 request, response를 예시를 볼 수 있다.

정상 호출 시 response

에러 발생 시 response

응답이 없어도 request, response 예시를 보여줄 수 있다. add Request로 만들고 싶은 API를 작성하고 ...클릭 → Add example을 선택해서 response를 설정할 수 있다.

아직 구현하지 않은 API 예시

postman으로 테스트해본 결과 만족스러운 문서를 얻을 수 있었다.

API 문서화를 할 때 API 구현 전에 API 문서 작업을 해야 한다면 postman을 사용하고, 문서화를 먼저 상황이 아니라면 API 구현 후 spring REST docs를 사용해보자!