API 문서 작성하는 방법

프로젝트를 진행하면서 API 문서를 작성하는 방법에 대해서 공부했다.

프로젝트 repository wiki에 업로드하여 팀원 모두와 공유하기로 하고 API document를 작성하는 방법에 대해서 검색을 해봤다. 그러던 중 좋은 자료를 발견하였고 이에 맞춰서 wiki를 작성했다.

(자료 출처 : gist.github.com/iros/3426278)

먼저 꼭 들어가야 하는 내용들이다.

• API Title - api 이름
• URL - api 경로
• Method - request 방식 (get | post | delete | put)
• Data Params - post 요청시 body안에 넣어줄 값
• URL Params (만약 있을 경우)
  • Required - url params로 넘길 값
• Success Response - 응답이 성공적으로 반환될 경우 반환되는 값과 코드
• Error Response - 응답이 성공적이지 못할 경우 반환되는 값과 코드
• Sample Call - 요청과 응답의 예시

다음과 같은 내용들은 꼭 들어가야 하는데 표로 작성해도 좋고 이렇게 글머리 표를 이용해서 작성해도 좋다.

이번에 나는 표를 이용하여 작성해보았다.

예시 자료

마크다운언어로 작성해서 올렸는데 생각보다 썩 이쁘게 나온 거 같지가 않았다. 

표의 크기를 조금 수정해서 올리는 것이 좋을 것 같다.