[TIL 2024. 05. 09] API문서 작성 (w. Notion)

DRF를 활용해서 레퍼런스용 게시글을 만들 수 있는 API 뉴스 사이트를 구현해보는 심화 팀 프로젝트를 진행하고 있다.

 

지금까지 프로젝트를 하면서 본격적으로 현업에서 하듯 API문서를 작성해본 것이 이번이 처음이다

지난 DRF 개인과제(Sparta_drf)에서도 API문서에는 endpoint랑 Method정도까지만 정리하고, 구체적인 Response는 Postman자체를 캡쳐해서 README자체에 이미지를 넣어주는 형태로 진행했었다.

 

오히려 현업에서 중요하고, 필수적인 것이라면 지금 팀 프로젝트를 해볼 때 경험해보는 게 좋겠다는 생각이 들어서 역할 분담시 자원해서 API문서를 담당하기로 했다

 

그리고 Postman보다는 Notion을 사용하는 것이 시각적으로 깔끔할 것 같아서 API문서는 노션으로 작성하고, 우리 팀 노션 내에서 API문서를 하위 페이지로 생성해서 이를 README내에 링크로 제공하기로 했다

 

그 결과, 작성한 API문서의 완성본은 다음과 같다

 

API 문서 | Notion

---

 

사실 Notion사용법에 능숙하지 못해서 약간의 좌충우돌이 있었다;;

그래서 새롭게 알게 된 노션 사용법, 특히 API문서 작성시 유용했던 기능들을 정리해보고자 한다

 

데이터베이스 생성 및 속성 편집

처음에는 표를 직접 열과 행을 지정해서 만들어줬는데, 그렇게 하니 속성 유형으로 "선택"을 사용할 수 없어서 데이터베이스로 쓰기가 어렵다는 생각을 했다.

 

그런데 알고 보니 "/표"명령어로 표 자체를 만드는 것과 데이터베이스의 기본 형태를 잡아주는 것을 선택할 수 있었다.

이렇게 데이터베이스를 선택하면 된다

그러면 이렇게 데이터베이스 기본 형태를 자동으로 잡아준다

 

(나중에도 언급하겠지만 이때의 빨간박스가 view를 추가하는 부분이고, 초록색 박스가 속성을 추가하는 부분이다)

 

---

 

 

그리고 각 필드를 생성하고, 원하는 제목을 적어주면 된다.

이때 중요한 것이 "속성을 지정"해주는 것인데, Endpoint와 Description을 제외하고는 "선택"속성을 아무래도 가장 자주 사용하게 될 것 같다.

 

실제로 이번에도 API문서를 작성할 때 Method, Authorization, API구분 필드에서 모두 "선택"속성을 사용하여 시각적으로 깔끔하게 정리할 수 있었다

 

 

실제 오늘 작성한 API문서

 

---

데이터베이스 구분

이번 프로젝트에는 Accounts, Articles앱이 있고, Articles앱 내에는 Articles에 대한 view 뿐만 아니라 Comments에 대한 view도 있어서 Postman으로 실행 테스트 시에도 Accounts, Articles, Comments의 3가지로 폴더를 나누어서 API를 관리했다.

 

그래서 자연스럽게 API문서를 작성할 때도 이 3가지로 테이블을 구분하고자 했다.

 

처음에는 Account에 대한 각 하위 페이지 작성까지 모두 마치고, 표 옆의 +버튼을 통해 테이블을 더 생성해서 Articles를 모두 작성하면 된다고 생각했고, 실제로도 그렇게 했다.

 

그런데 Articles에 대한 API 하위 페이지까지 모두 작성하고, Account로 돌아가보니 이전에 작성한 Accounts관련 내용이 모두 날아가고, Articles에 대한 내용으로 Accounts까지 대체되어 있었다ㅜㅜ

 

그래서 매니저님께 노션 사용과 관련해서 여쭤본 결과, 표 옆의 +버튼을 통해서 추가 생성하는 것은 "view"이므로 일단 처음에는 Accounts, Articles, Comments 이렇게 항목을 구분하려고 하지 말고, 전체 API를 하나의 테이블 내에 쭉 정리하고, 각 항목에 대해서 "필터"를 지정해서 구분하는 방식을 추천해주셨다

 

이 외에도 각 항목마다( Accounts, Articles, Comments) 데이터베이스 자체를 각각 생성해주는 방법도 존재하긴 하지만 품이 너무 많이 들기도 하고, 시각적으로 매니저님이 권해주신 방법이 더 깔끔하고 가독성이 높은 방법인 것 같아서 필터를 걸어주는 방식으로 진행했다

 

즉, "API 구분"이라는 필드를 새롭게 만들어서_이를 기준으로 필터를 지정해줬다!

 

필터 걸기 전의 전체 API 테이블

---

노션 Inline Block

각 Endpoint의 Method마다 작성하는 하위 페이지에는 해당 기능에서 요구되는 Auth기능이 뭔지, Request의 Header와 Body에는 어떤 데이터를 어떤 형식으로 보내야 하는지, 그리고 Response는 어떤 형태로 어떤 항목을 반환하는지를 명시해줘야 한다

 

특히, Request의 Header와 Body에 어떤 항목(주로 key-value)이 들어가는지를 작성해줄 때, 노션이 제공하는 Inline Block을 사용하면 시각적으로 깔끔하고 예쁘게 정리할 수 있다

 

Inline Block을 사용하는 방법은 간단하다

Inline Block을 지정해주고 싶은 각 문자열을 백틱(``)으로 감싸주기만 하면 된다

 

빨간 박스가 Inline Block을 사용한 부분이다