안녕하세요!
오늘은 API 명세서 작성법에 대해 정리해보려고 해요.
백엔드 개발자로서 협업을 하다 보면 API 명세서를 만들 날이 오는데요...!
프론트엔드 개발자가 백엔드 개발자가 작성한 라우터 관련 코드를 보고 어떤 백엔드 서버 주소로,
어떤 정보를 보내줘야 하는지, 그러면 어떤 정보가 오게 되는지 파악하기란 쉽지 않을 수 있어요.
그래서 협업 시에 API 명세서를 만들어서 프론트엔드에게 제공해주어야 해요.
또한 백엔드 개발 과정에서 자신의 코드가 잘 작동하는지 확인용으로 쓸 수도 있어요.
생각보다 쉽게 만들 수 있으니 따라해 보세요!
저는 API 명세서를 만들기 위해 Postman을 추천받아 사용했어요.
1. 포스트맨 다운로드
https://www.postman.com/downloads/
Download Postman | Get Started for Free
Try Postman for free! Join 25 million developers who rely on Postman, the collaboration platform for API development. Create better APIs—faster.
www.postman.com
위 사이트에 접속해서 자신의 운영체제에 맞는 방법으로 다운로드 한 후 회원가입을 해주세요.
2. Workspace 생성
새로 워크스페이스를 생성하거나 기본적으로 만들어져있는 My Workspace에 진입해주세요!
3. Collection 생성
New 버튼을 누른 후 Collection을 눌러서 Collection을 생성해 주세요!
Collection 이름을 자신의 프로젝트 이름 등으로 수정해주세요!
저는 제가 하고있는 프로젝트 웹사이트 이름인 Rangpid로 해줬어요.
이 Collection이 어떤 api 정보를 모아놨는지에 대한 설명서를 작성해주세요.
4. Request 생성
저는 로그인, 회원가입, 사용자 정보 조회 등을 테스트 하기 위해 각각의 Request를 생성해줬어요!
5. Get 요청 보내기
필요한 정보들을 입력하고 send버튼을 누르면 결과를 확인할 수 있어요!
(백엔드 서버를 실행시킨 상태에서 진행해주세요!)
Save 버튼을 눌러 저장
6. POST 요청 보내기
Body에 보낼 정보들을 입력해주세요!
Save 버튼을 눌러 저장
7. PUT 요청 보내기
필요한 정보들을 입력해주세요!
저는 Authorization도 필요해서 해줬어요!
8. 예시 추가하기
자 이제 필요한 모든 요청들의 기본적인 걸 작성했다면 추가적으로 예시도 작성해줄게요!
아까 만든 요청에 들어가서,
Body의 데이터 값이나 경로 변수들을 바꿔가면서 Send를 하고 Save as example을 눌러주세요!
그리고 나서 Rename을 클릭해 예시의 이름을 써주세요.
이렇게 각각의 요청별로 여러 예시들을 만들어주면 request와 respond가 여러 가지 상황에서 어떻게 오고 가는지 잘 파악할 수 있겠죠?
9. 명세서 공유하기
이제 마지막이에요!
우측 하단의 이 버튼을 클릭해주세요!
우측 상단의 Publish 클릭!
나타난 페이지에서 publish 클릭!
URL을 복사해서 카톡이나 이메일 등으로 다른 사람에게 공유하면 완료입니다:)
수고하셨어요!!!