Api 문서 자동화에 대한 개인적인 노력과 후기...

 

협업에 없어선 안 될 문서가 api 문서이다. 백엔드와 프론트엔드가 보통 분리되어 작업하기 때문에, 프론트엔드 개발자가 문서만 보고! 작업할 수 있게, 쉽게! 잘! 작성해야한다.

 

2021년 프로젝트를 하면서, 나도 당연히 api 문서를 작업해야했는데, 적절한 툴을 찾지 못해 많이 불편했다. 처음엔 사내에서 사용중인 Jira의 공유 문서를 사용했고, 두번째 프로젝트에선 구글 doc, 한번은 엑셀도 사용해봤다. 심지어 에버노트도 한번 추라히 해봤다. 그.러.나. 너~~무 불편했다. 기본적인 문서툴은 거의 다 불편했다.

 

개인적으로 올해 사용했던 툴과 사용 후기를 적어보았다.

api문서 자동화기능인 swagger, apidoc등 도 한번 사용해봐야지!

---

목차

---

Api 문서가 꼭 가져야 할 점 (뇌피셜)

• 가독성이 좋아야함.
  • 문서만 보고도 대화하듯이 술술 읽여야함. (이건 개인 능력치일듯)
  • 거슬리지 않는 깔끔한 스타일
• 공유가 편해야함.
  • 대부분 프로젝트가 애자일이기 때문에 서버 환경이 바뀌는 대로 프론트엔드 개발자가 바로바로 확인할 수 있어야 함
  • 매번 파일을 공유하는 것도 일이다. url 공유하고 바로 바로 확인할 수 있는게 가장 좋은듯.
• 인덱스 기능
  • 필요한 api 섹션에 바로 바로 찾아갈 수 있는 인덱스 기능이 거의 필수인 듯. 없었을 때 프론트엔드 개발자가 힘들어 했다.
  • 관련된 api, 사내 메모 섹션에 바로 찾아 갈 수 있으면 플러스!

Api문서가 가질 기능으로 꼭 필요한 점을 몇가지 적어보았다. 그 중에서도 "공유"기능이 가장 중요한 듯. 본질 of 본질 아닐까...

각 포맷별 장단점

기본 엑셀

🥰 익숙하다

🥰 별도로 설치할 필요가 없다.

🥰 한눈에 파악하기 좋다.

😡 공유가 힘들다.

매번 파일을 메신저로 전달해야함. → 구글 스프레드 시트로 해결 가능

애자일 문화와 제일 안 어울리는듯.

😡 코드 블럭이 없음.

코드 포맷을 매번 수정해야함.

😡 목차 기능이 없음.

목차 생성한다면 할 수 있지만, 이렇게 스타일을 신경쓰느라 더 시간이 걸린다.

Jira 공유 문서 기능

🥰 url로 공유 가능하다

🥰 기본적인 edit 툴이 편함

목차 기능, 코드블럭, 개발 언어 설정, 마크다운 지원, 심플 테이블 기능 등 꽤 편리한 기능이 많음.

🥰 UI 심플하니 괜찮음

😡 바뀔 때마다, 느린 Jira 사이트 접속해야함.

그리 귀찮은 작업은 아니지만, Jira 사이트가 느려서 접속할때마다, 번거로웠음.

😡 협업 툴이 바뀌면 어떻게 관리함?

만약 회사 엽업툴이 바뀌면, 마이그레이션해야한다는 단점... 번거롭다.

그러나 이 문제는 모든 툴이 가지고 있는 문제일 듯.

😡 pdf화가 그리 자연스럽지 않다.

문서로 내보내거나, pdf로 제출할 경우, 결국 2차 수정이 필요함.

에버 노트

🥰 url로 공유 가능하다

🥰 기본적인 edit 툴이 편함

😡 코드 블럭이 있으나 마나

코드블럭에 언어별 스타일이 적용이 안되니 말짱 도루묵. 폰트도 작아서 별로.

😡 워크플레이스 분리가 애매하다.

노션은 웹페이지같이 부모 페이지, 서브 페이지 형식으로 분리할 수 있는데, 에버노트는 서브 페이지 개념이 없음.

때문에 뭔가... 뭔가... 2프로 부족한 느낌

노션

노션은... 사내 규정을 명시하거나, 인사이트 공유, 문서 공유에 최적화 되었다. api 문서 공유용은 아닌듯.

🥰 깔끔한 UI

🥰 기본적인 edit 툴이 편함

🥰 코드 블럭이 제일 좋은듯

😡 심플 테이블 기능이 없다

→이번 업뎃으로 기능이 추가됨. 써봤는데 아직 부족하다. 표 편집이 너무 제한적이다.

제일 불편하다. 노션에선 표의 개념이 "데이터 베이스"라 굳이 싶음.

구글 doc

🥰 url로 공유 가능하다

🥰 협업이 가능함.

기본적으로 서로 문서를 편집할 수 있어서, 협업할때 유용.

🥰 기본 구글 doc기능의 편리함

히스토리, 목차 생성, 템플릿 생성, 권한 설정 등 기본적으로 구글이 제공하는 기능이 협업에 유용함.

특히 왼쪽에 제목별 하이퍼링크가 생기는데, 한눈에 api를 살필 수 있어 좋았음.

🥰 높은 자유도

일반 문서이기 때문에 api뿐만아니라 다양한 노티 및 메모가 가능함.

🥰 출력 디자인이 ㄱㅊ

일반 문서툴은 파일 포맷을 변환했을때 디자인이 크게 변하지 않아서 좋았음.

😡 한눈에 볼 수 있는 양이 적다.

😡 코드 블럭이 없다.

기본 문서툴의 공통적인 최대 단점... 코드 블럭 기능이 없다는 점.

코드블럭이 없으면 일단 가독성이 많이 떨어지고, 스타일을 설정하는데 시간을 많이 뺏긴다.

→ 추가 기능으로 코드 블록을 넣을 수 있음. 그런데 조금 느림. 기능은 좋다. 추천 추천~

😡 빠르게 바뀌는 프로젝트를 반영하기 어려움

이 단점도 공통적인 단점. 안그래도 바빠 죽겠는데, "코드작업 → 문서작업" 함께하기 너무 어려웠음.

Postman (맛보기로 사용함)

🥰 개발 테스트하면서 사용하기 좋음

🥰 json 파일로 export 가능함

😡 문서화 기능은 유료

로그인하고, 팀 설정해야 문서화 가능한 걸로 알고 있음. 귀찮아서 안 써봄.

 

Swagger (맛보기로 사용함)

🥰 개발하면서 별도 창 없이 개발 환경에서 수정가능하다.

😡 디자인이 별로다...

😡 주석이 너무 늘어나 지저분해짐. (개취인듯)

개인적으로 스웨거를 별로 안좋아하지만, 한번정도 써볼만 한듯.

 

---

전체적인 후기

기본적인 문서툴 (엑셀, 구글doc 등)은 높은 자유도와 pdf변환시 자연스럽다는 점, api문서뿐만 아니라 유동적으로 노티를 추가할 수 있다는 점이 강점이었다. 그러나 공통적으로 코드 가독성을 설정하는게 어렵고, 전체 템플릿을 설정하느라 시간소요가 된다는 점이 단점이다.

외부 툴(Jira, 에버노트, 노션, postman 등)은 일단 유료인 경우도 있고, 툴에 따라 무거움 정도가 달랐다. 또! 왜! pdf화 하면 스타일이 깨지는지 모를일이다...

남은 연휴동안 swagger나 apidoc을 사용해보고 후기에 추가해야겠다. 스웨거 등 api문서 자동화 라이브러리를 사용하면 어노테이션이 과하게 많아져 코드 가독성이 떨어진다는 단점도 있다고 한다. 아 어렵다 어려워~~ 어디 딱 좋은 툴이 갑자기 자기소개하면서 와줬으면 좋겠다. 아니면 한번 만들어볼까? 크크

---

api 문서화에 필요한 점

• url 기반의 편리한 공유 기능
• 프라이빗하게 공유할 수 있으면 더 좋음
• pdf 및 doc으로 추출시 깨지지 않으면 더 좋음!
• 코드 블럭 기능을 통해 가독성 높이기
• 가독성 좋은 UI, 심플 테이블 기능
• 문서화 작업에 시간을 많이 쏟지 않아도 될 편리함
• 전체 프로젝트에 대한 설정값, 설명을 추가할 수 있음 좋겠음
• api url별 설명을 추가하기 편하면 좋음
• 프로그램이 가벼웠음 좋겠음
• 목차 기능은 필수!!