API 명세서 만들기

악어·2022년 9월 29일

얼마전, 제가 만든 앱 '카페자리'를 플레이스토어에 런칭했습니다. 프론트/백엔드 거의 제가 혼자 만든 앱인지라 애착이 가는 앱인데요, 문득 이런 생각이 들었습니다.

개발할때 변수 설정등의 기초적인 부분부터 rest api 설계까지 저 혼자 알아볼 수 있게, 그저 돌아가게 만들어 놓은 부분이 많아 더더욱 이런 생각을 지워낼 수 없었습니다.

물론 아무런 소득없이 조용히 앱이 잊혀진다면(대개 그렇게 되죠..) 더 걱정할 필요는 없겠지만, 그래도 개발자로서 협업을 준비한다는건 그 자체로 의미있는 일이라고 생각했습니다. 그래서 해본 생각..

api명세서를 통해 프론트 개발 인원과의 협업 효율성을 높이고, 제가 ios앱을 개발할때 써먹을 수 있게 하자는 것이 목표였습니다. 그 과정을 여기에 정리해보겠습니다.

1. 툴 선정

POSTMAN으로 선정!

어떤 기획이 그렇듯 우리의 영원한 동반자 구글에 api 명세서를 검색해봤습니다. 여러가지 추천 방식이 있었는데, 제가 원하는 바는 다음과 같았습니다.

위 조건을 기준으로 추려본 결과 많은 사람들이 추천한 postman이 가장 적합했습니다.

2-1. 온라인 연동

위는 postman의 workspace입니다. 같이 작업하는 친구를 초대해놨는데요, 보시다시피 팀 워크스페이스와 개인 워크스페이스를 구분하고 깃허브처럼 서로 실시간 연동이 가능하다는 장점이 있었습니다.

2-2. API REQUEST 테스트가 가능할 것

postman을 써보신 분들이라면 당연히 아시겠지만, request를 설정해놓고 테스트해보기 좋습니다.

카페자리 서버같은 경우에는 JWT토큰을 인증 수단으로 사용하기에, header에 authorization을 설정하여 access_token을 전달해줘야 제대로된 응답을 받을 수 있습니다.

이때 postman의 전역변수 설정을 통해 유효기간이 무한한 access_token을 하나 설정해놓고, request에 동봉해 실제 서비스와 같은 응답을 받을 수 있도록 설정할 수 있다는 점이 정말 편했습니다.

액세슨 토큰을 전역변수 main_access_token으로 설정한 모습

이로써 직접 요청을 보내고 응답을 받으면서 쉽게 이해할수 있겠죠?

2-3. 사용성이 쉬울것 / 쉽게 문서화 가능할것

사용성은 솔직히 새로운 툴을 다루는 것이니 낯설기는 했습니다. 하지만 많은 사람들이 쓰는 툴인만큼, 모르는 기능은 대충 검색해봐도 정보들이 넘치게 나오더군요. 조금만 익숙해지면 쓰기 좋을거에요!

문서화의 경우 다음과 같이 하시면 됩니다.

documentation으로 보기를 들어가신다음,
오른쪽 위 publish를 눌러주시면...! (저는 이미 발행한 상태입니다)

이렇게 한눈에 보기에도 깔끔하게 문서화된 api 명세서를 얻을 수 있습니다. 저같은 경우에는 주석과 sample response를 자세하게 정리해놓았기 때문에, 여러가지 상황에 대한 응답을 확인할 수 있었습니다.

보시는 것처럼 여러가지 이유로 회원가입이 거부되는 상황을 등록해놓았죠. 이처럼 보기 쉽게 주석, 요청, 응답, 예시등을 등록할 수 있다는 것이 postman의 큰 장점인것 같습니다!

저처럼 api 명세서를 통해 협업을 준비하시는 분들이라면, 쉽고 편하게 사용할 수 있는 postman을 적극 추천합니다~!!

냅다 회사부터 세워버린 개발자