API Documentation
API 문서화의 목적과 사용의의
- API 문서화란 백엔드가 작성한 각각의 API 기능을 문제없이 사용하기 위해서, 개발자간 어떠한 구성 요소를 주고 받아야하는지 일목요연하게 정리하는 작업
- 구두 또는 수기로 작성한 문서로 주고 받기에는 불편함이 많음
- 개발 작업 특성상 서로간 공유해야하는 수많은 내부 요소들이 있고, 이들 중 단 한 개라도 누락이 되면 정상 기능을 방해하는 오류가 발생 -> 불편함을 해소하고자 많은 개발자들이 API를 자동으로 문서화 할 수 있는 방안을 고안
- 서로의 통신 내용을 직관적으로 파악할 수 있게끔하는 웹 개발자의 필수 보조 작업물
API Documentation 장점
1. 개인의 장점
- 자신의 작업물을 다른 사람과 보다 효율적으로 공유할 수 있다는 점
- API 기능정의서에는 목적, 의도, 엔드포인드, API별 필수 인자 등에 대한 세부 정보가, 개발자는 물론 일반 사용자 까지 모두 이해하기 쉬운 형식으로 구조화되어있습니다.
- 기능 설명서는 개발자 개인이 직접적으로 타인과 소통해야만 하는 빈도를 확연히 줄여줄 수 있고, 그 결과 일의 능률을 높일 수
있습니다.
- 또한 사용자로 하여금 다양한 요청-응답 방식을 더 잘 이해할 수 있게 관련 예제나 영상도 같이 업로드 하기도 하는데, 이는 초기에 소비한 시간 이후 비용은 최소화됨을 의미합니다.
2. 기업의 장점
- 새 사용자들이 익숙해지기까지 소요되는 평균 시간을 줄여줍니다. 복잡한 API 구조의 서비스를 제공하는 다양한 기업들이, 더 많은 사용자를 유치할 수 있는 전략으로 사용됩니다.
- 사용자에게 API를 구현하기 전 미리 시험해볼 수 있는 기능을 선제공할 수 도 있으며, 직접 API를 사용하는 팀의 경우, 해당 기업에 궁금한 점들을 직접 질문하기 위해 연락하는 시간과 빈도를 줄여줄 수 있습니다.
- API 문서화는 우수한 상태의 제품 유지 관리로 이어집니다. 개발부서 모든 팀이 실시간으로 반영되는 리소스, 방법, 관련 요청 - 응답에 대한 세부 정보를 공유한 상태라고 가정한다면, 관련 API에 대한 유지,관리,업데이트 등을 더 효과적으로 수행할 수 있게 됩니다.
API Documentation을 이루는 필수 요소
- 해당 API의 사용 예시
- URI (엔드포인드)
- 샘플 REQUEST 양식
- Request parameter
- Response parameter
- 에러 핸들링 정보
- Etc
Postman을 사용하여 api documentation 을 해보겠습니다. (SwaggerHUB도 인기가 좋다고..)
Postman을 이용한 API Documentation
1. postman을 설치하고 실행 후 메인 홈 화면 좌측 workspace 란을 확인합니다.
2. New Workspace 박스를 클릭하면 아래의 내용과 같이 새로운 WorkSpace를 생성할 수 있습니다. 이 때 자신이 맡은 프로젝트와 관련된 팀이름 또는 프로젝트명을 활용하여 WorkSpace명을 짓고 간략한 설명문을 작성합니다.
3. 이후 새롭게 페이지가 하나 생성됩니다. 좌측 Collection 부분의 + 버튼을 클릭하여, 새로운 API Collection (모음집)을 만듭니다. 그 후 소속된 프로젝트와 동일한 명칭등, 팀원들끼리 사용 하기에 적절한 Collection 명칭을 지어 줍니다.
4. 새로운 Collection 페이지 내부 좌측 배너에서 새로운 http request를 생성합니다. 이 후 http 메소드를 설정하고 원하는 URI를 주소란에 치면 내가 의도한 통신 요청을 보낼 수 있습니다. 요청이 성공한 이후에는 아래와 같이 반환된 결과값도 확인해봅니다.
5. 이후 우측 하단에 Save Response 영역 내부에 있는 save as example 버튼을 클릭하여 해당 내용을 Collection의 예시로서 저장해줍니다. 이 절차를 따라야만 추후 문서화 작업시에 내가 원하는 API 내역으로 저장 및 추가 할 수 있습니다.
6. 이후 좌측 배너 우상단의 *** 표시를 클릭하여 View Documentation 버튼을 클릭합니다. 이후 내가 작성한 요청들을 정리한 내역들이 우측 화면에 노출되면 내가 의도하여 작성한 내용이 맞는지 확인합니다.
7. 이후, 좌측에 example 형식으로 저장된 내 요청들과 example로 저장된 하위 목록들을 들어가서 살펴 본 후 우측 상단의 publish 버튼을 클릭합니다.
8. 이후 화면은, 내가 작성한 API 들을 documentation 관련 내부 요소를 상세 설정할 수 있는 페이지로 전환됩니다. 모든 내역을 내가 의도한대로 설정하신 이후 하단의 publish 버튼을 클릭하여 최종적으로 배포를 마무리 합니다.
9. 이후 Publish 된 API Documentation 관련 링크가 아래 사진과 같이 출력됩니다. 해당 링크를 클릭하여 접속합니다.
10. Postman에서 제공하는 API Documentation의 생김새는 아래와 같습니다. 이 때 주의할 점은 http 통신에 맞게 상단의 language 부분이 http로 올바르게 선택되었는지 확인하는 것 입니다. 우측 검정색 바탕의 내용을 토대로 클라이언트/프론트와 통신시 예상되는 요청 값, 기대하는 리턴 값을 상세히 확인 합니다. 모든 내역이 의도한대로 작성되었다면 배포된 해당 페이지 링크를 프론트엔드(혹은 다른 개발자)에게 공유합니다. 필요에 따라서 좌측 각 API 별로 설명 내용을 상세히 적어 다른이의 이해를 적극적으로 도울 수 있습니다.
11. API 문서가 Publish 된 이후에는, 7번 과정에서 “publish”로 보여지던 우측 상단 버튼이 배포 됬음을 의미하는 “published”로 바뀐 것을 확인 할 수 있습니다. 그리고 해당 버튼을 클릭하게되면 (1) 해당 페이지로 이동할 수 있는 URL 과 (2) 세부 설정내용 편집란으로 이동할 수 있는 두 옵션을 확인할 수 있습니다.
이렇게 api 문서화 목적과 의의, 장점, 그리고 Postman 사용법에 대해 알아보았는데요.
기업에 들어가게 되면 어떻게 api가 문서화 되었는지 확인하면 좋을 것 같습니다.