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 란을 확인합니다.

 

workspace 위치

2. New Workspace 박스를 클릭하면 아래의 내용과 같이 새로운 WorkSpace를 생성할 수 있습니다. 이 때 자신이 맡은 프로젝트와 관련된 팀이름 또는 프로젝트명을 활용하여 WorkSpace명을 짓고 간략한 설명문을 작성합니다.

workspace 생성 페이지

3. 이후 새롭게 페이지가 하나 생성됩니다. 좌측 Collection 부분의 + 버튼을 클릭하여, 새로운 API Collection (모음집)을 만듭니다. 그 후 소속된 프로젝트와 동일한 명칭등, 팀원들끼리 사용 하기에 적절한 Collection 명칭을 지어 줍니다.

Collection 생성

4. 새로운 Collection 페이지 내부 좌측 배너에서 새로운 http request를 생성합니다. 이 후 http 메소드를 설정하고 원하는 URI를 주소란에 치면 내가 의도한 통신 요청을 보낼 수 있습니다. 요청이 성공한 이후에는 아래와 같이 반환된 결과값도 확인해봅니다.

Postman을 이용한 통신 성공

5. 이후 우측 하단에 Save Response 영역 내부에 있는 save as example 버튼을 클릭하여 해당 내용을 Collection의 예시로서 저장해줍니다. 이 절차를 따라야만 추후 문서화 작업시에 내가 원하는 API 내역으로 저장 및 추가 할 수 있습니다.

Postman 통신 성공 내역 예시로 저장

6. 이후 좌측 배너 우상단의 *** 표시를 클릭하여 View Documentation 버튼을 클릭합니다. 이후 내가 작성한 요청들을 정리한 내역들이 우측 화면에 노출되면 내가 의도하여 작성한 내용이 맞는지 확인합니다.

Documentation 생성 내역 확인

7. 이후, 좌측에 example 형식으로 저장된 내 요청들과 example로 저장된 하위 목록들을 들어가서 살펴 본 후 우측 상단의 publish 버튼을 클릭합니다.

Documentation Publish 버튼 위치

8. 이후 화면은, 내가 작성한 API 들을 documentation 관련 내부 요소를 상세 설정할 수 있는 페이지로 전환됩니다. 모든 내역을 내가 의도한대로 설정하신 이후 하단의 publish 버튼을 클릭하여 최종적으로 배포를 마무리 합니다.

publish 상세 설정

9. 이후 Publish 된 API Documentation 관련 링크가 아래 사진과 같이 출력됩니다. 해당 링크를 클릭하여 접속합니다.

Documentation Publish 링크 확인

10. Postman에서 제공하는 API Documentation의 생김새는 아래와 같습니다. 이 때 주의할 점은 http 통신에 맞게 상단의 language 부분이 http로 올바르게 선택되었는지 확인하는 것 입니다. 우측 검정색 바탕의 내용을 토대로 클라이언트/프론트와 통신시 예상되는 요청 값, 기대하는 리턴 값을 상세히 확인 합니다. 모든 내역이 의도한대로 작성되었다면 배포된 해당 페이지 링크를 프론트엔드(혹은 다른 개발자)에게 공유합니다. 필요에 따라서 좌측 각 API 별로 설명 내용을 상세히 적어 다른이의 이해를 적극적으로 도울 수 있습니다.

Publish 배포 문서 확인 및 공유

11. API 문서가 Publish 된 이후에는, 7번 과정에서 “publish”로 보여지던 우측 상단 버튼이 배포 됬음을 의미하는 “published”로 바뀐 것을 확인 할 수 있습니다. 그리고 해당 버튼을 클릭하게되면 (1) 해당 페이지로 이동할 수 있는 URL 과 (2) 세부 설정내용 편집란으로 이동할 수 있는 두 옵션을 확인할 수 있습니다.

Publish 상태 확인

 

이렇게 api 문서화 목적과 의의, 장점, 그리고 Postman 사용법에 대해 알아보았는데요.

기업에 들어가게 되면 어떻게 api가 문서화 되었는지 확인하면 좋을 것 같습니다.