필요성의 자각
Spring 프로젝트를 백엔드 용도로 진행하면 API 문서를 작성해야만 한다.
대학에서 그렇게 논문을 쳐다보던 사람이 개발자가 되서는 문서의 효율성을 모르는 사람마냥 여기는 사람이 많더라.
API 문서는 사용자의 입장에서 최대한 질문이 없도록 꼼꼼하게 써야하고, 필요한 내용이 있으면 업데이트를 해야만 한다.
프로젝트를 추후에나 혹은 새 인원이 참가하는 경우에도 인수인계를 최소한으로 할 수 있을만큼 작성되어야 한다는 것.
그리고 API 문서는 개발 진행 당시에도 중요하지만 최종 산출물이기도 하다.
좋은 API가 무엇인가를 좀 더 알고 싶다면, LINE 형님들이 쓴 글을 읽어보면 도움이 된다.
그 동안에는 어떻게 쓰였는가?
1) 문서 프로그램으로 작성
초기에는 심한경우는 Excel(물론 정리되어 있진 않다, 흔히 말하는 나쁜SI의 대충 산출물)이나 Docx로 만드는 때가 있었다. 잘 만들어진 경우는 다음과 같은 사진 처럼 어느정도 틀은 잡아두고 사용자가 스크롤을 내리면서 봤었다. PDF로 배포해주더라도 이게 최종본인지 알 수도 없고, 사실상 한 눈에 안들어온다. 마음적으로 여유가 많은 사람들이나 꼼꼼하게 읽어보지 않았을까 한다.
Excel로 만들면 시트가 너무 많아 탈이고 어느게 어느 항목인지 보려면 그 항목이 포함된 메뉴구조도 같은 시트에서 찾아야하는 번거로움... Docx는 목차가 있어 따라가긴 편하지만 Microsoft의 특유의 문제 때문에 프리징 걸리는건 참을수가 없다..
2) Postman과 같은 툴의 등장
Postman및 유사 프로그램들은 공통적으로 지원하는 기능이, API를 Send 해 볼수 있고, 최근에는 Websocket, Stomp까지 지원한다. 추가로 문서를 추출할 수 있는 기능까지 하고 있는데, Collection을 Publish 하는 순간 생겨나고 화면은 아래와 같다. 17년도 부터였던가.. 오래 쓰고 있지만 정은 그리 가지 않는다.
Postman의 단점은, Parmaeter가 어떤 Type이고(String과 Enum을 헷갈리는 사람도 많다) 화면마다 존재하는 View More버튼 때문에 누르게 되면 화면이 꽉차 아무것도 안보이는 문제는 사용성을 떨어뜨리게 만든다. 개발자 끼리는 Postman 문서를 전달할수 있겠으나 개발자 끼리라면 차라리 Collection을 Export해서 주지 않을까? 그런데 나는 이 방법도 별로 추천하지 않는다. 이유는 Collection 동기화 때문에 돈 쓰는게 너무 아깝다... 그리고 그만한 돈을 주면서 써야 할 협업 프로그램인가에도 의문이 든다.
결과적으로 사용하기에 이쁘지도 않고(잘 정리되지 않은) 사용성이 떨어진다.
3) Slate 유사 MD 기반 Viewer
Slate는 Ruby 기반에서 작동하는 MD Viewer라고 보면 되는데 Slate내에서 제공하는 스타일가이드는 UI가 이쁘게 나오긴 한다. 내용이 필요하면 MD를 더 만들거나 편집해서 쓰면 되긴 하나, 아무래도 설치 과정이 꽤 맘에 들지는 않는다.
그 외에는 Swagger랑 연결하려면 일반 Slate가 아닌, Widdershins나 ReSlate를 써야해서 러닝 커브 뎁스가 또 깊어지는건 마찬가지다.
4) OpenAPI Viewer
본인이 OpenAPI 를 yml, yaml, json 등으로 배포를 할 수 있는 상황이라면 (Swagger 같은 툴로) Viewer만 따로 사용하는것도 나쁘지 않다. 이 방법이 나쁘지 않은게, OpenAPI를 배포할 수 있는 상황이라는 것은 개발 하면서 문서를 제작할 수 있는 상황이라는 뜻이기 때문이다. Viewer를 설치하는건 따로 어렵지도 않고 배포할 것도 없다.
예를들어 Redoc이라는 것이 있다.
5) 논외, Gitbook
Gitbook은 Github와 같은 Repository에서 md로 관리할수 있게끔 지원하는데, Gitbook에서 표현되는 테이블이라던가 탭이라던가 이러한 것들은 따로 문법이 존재하고 (지원하려면 VS나 IntelliJ에서 Plugin으로 따로 주던가.. 내가 못찾나?)
제일 못난건 Prev Page, Next Page 버튼이 항상 표시되는것. 느린 반응성, 한글 칠때마다 마지막 글자 짤림(Postman Post Body 에 한글치는것 처럼)이 너무 심해서 쓰지 못하겠더라.. Gitbook을 잘 쓰는분들이 있으면 한 번 어떻게 쓰는지 보고 싶긴하다. 이러한 것들을 참고 쓰신다고?
그래서 뭘 쓸건데?
필자는 Swagger로 따로 OpenAPI를 관리하면서, Redoc을 Webserver에 설치해서 쓰는 쪽을 택했다.
사실상 API 개발만 따로 진행하는것 보다는, API와 문서를 동시에 진행하면 제일 좋은것이라 생각하기 때문이다.
Spring 진영에서는 예전부터 springdoc 혹은 springfox와 같은 라이브러리들이 이를 지원해주었다. (springfox는 지원중단 되었지만.)
그래서 다음 글에서는 springdocs을 진행하면서 개발 문서를 좀 쉽게 쓰기위한 커스터마이징 방법을 알려주려고 한다.
