[문서작성] API 명세서

📌 우당탕탕 회사 개발일지

 

 

API명세서 작성하기

 

 

이전까지 회사에서 API 명세서를 작성하지 않고 있었기 때문에, 과거 작업들에 대한 프로젝트들의 API 명세서를 작성해달라는 업무를 받았다. 이 때 내가 작성한 API명세서를 작성한 방법을 적었다!

 

 

 

 

1. 블로그 참고

 

API 명세서를 작성하는 방법은 여러가지이기에, 내가 생각했을 때 가장 적합하다고 생각한 블로그를 참조한다.

 

https://velog.io/@director20844/API-%EB%AA%85%EC%84%B8-%EC%9E%91%EC%84%B1%ED%95%98%EA%B8%B0

API 명세 작성하기

 

 

 

Q) 어느 문서 툴을 이용하는 것이 적합한가?

 

처음에는 Swagger, Notion, ... 너무나 새로워진 다양한 툴들이 많이 사용되고 있기에, 나도 따라가볼까라고 고민했었다. 하지만 회사사람들이 보기에 가장 보기 편하고 익숙하고, 누구나 접속해서 볼 수있는 쉬운 방법을 선택하는 것이 맞다고 판단했기에 엑셀로 작업하는게 맞다고 판단했다.

 

Q) 내용은 어느것이 들어가는 것이 맞는가?

 

다양한 블로그들을 보니 엄청 간편히 method와 endpoint만 작성하는 블로그도 있었고, 정말 자세히 res를 받았을 때 오는 변수명까지 자세하게 기입하는 블로그도 있었다. 하지만 난 이전까지 작업해왔던 프로젝트의 모든 API들을 정리해야 했기에 다른 사람들이 봤을 때 어느정도 이해는 되야하게 작성해야 했지만, 시간관계상 너무 자세하게 적을 수는 없었다.

 

 

 

 

내가 정한 열은 페이지, 기능 설명, 메소드, 엔드포인트, 입력데이터, 반환데이터, 비고로 정했다.

 

기능 설명 - 이 api의 기능에 대한 설명

메소드 - 어느 방식으로 통신했는가

엔드포인트 - api의 맨 끝 지점

입력데이터 - 클라 -> 서버 줘야하는 데이터

반환데이터 - 서버 -> 클라 주는 데이터 및 http 통신 방법

 

 

2. cursor ai 이용

 

이 방대한 양의 API를 언제 다 정리할지 막막하던 찰나에 파트장님께서 cursor를 이용해서 작성하는 것이 어떻겠냐는 제안을 주셨다.

API 컴포넌트화해서 모아서 작업했어야하지만, 늘 시간에 쫓겨 작업하다보니 중간에 따로 선언하는 부분도 많았고 과연 잘 정리해줄지

의문이 들었지만 활용해보기로 결정했다.

 

 

cursor는 생각보다 디테일하게 api명세서를 만들어줬다. 하지만 놓친 API도 많았고, 기능설명이 맞지 않는 부분도 많아서 100% 신뢰할 순 없었으나 작업속도는 훨씨 빠르게 진행될 수 있었기에, cursor를 이용하는 것또한 추천하는 방식이다.