백엔드는 해당 엔드포인트에 대한 최종 설명문인 API document를 작성
API 문서화 = 백엔드가 작성한 각각의 API 기능을 문제없이 사용하기 위해서, 개발자간 어떠한 구성 요소를 주고 받아야하는지 일목요연하게 정리하는 작업
API 기능정의서: 목적 / 의도 / 엔드포인트 / API별 필수 인자 등에 대한 세부 정보가, 개발자는 물론 일반 사용자 까지 모두 이해하기 쉬운 형식으로 구조화
직접적으로 타인과 소통해야만 하는 빈도를 확연히 줄여줄 수 있고, 그 결과 일의 능률을 높일 수, 기업 측면에서도 시간 및 비용의 효율 올릴 수
workspace를 만듦
여기 body에 적고
view documentation 로 들어가서 보면,
오른쪽에 목차 타고 들어가서 볼 수 있음
여기는 프론트에게 설명을 적는 란
API Documentation의 구성 요소
- 해당 API의 사용 예시
- URI (엔드포인트)
- 샘플 request 양식
- request 파라미터
- 샘플 response 양식
- response 파라미터
- 에러 핸들링 정보
API를 문서화해주는 외부 도구는 현재 시중에 여러 종류가 출시
가장 인기가 많은 9가지 문서화 도구 :
[ReDoc.ly, SwaggerHUB, Stoplight, ReadMe, Postman, LucyBot, DocGen, DapperDox, WidderShins].
- 참고링크(1): Swagger 공식문서 페이지
- 참고링크(2): ReDoc 공식문서 페이지
- 참고링크(3): Postman 공식문서 페이지
Postman을 이용하여 API 문서화 작업
주니어 개발자가 쉽게 접할 수 있고, 그 러닝 커브가 현저히 낮음
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. GET 요청외에도 아래의 POST 예시와 같이 CRUD에 해당하는 다른 메소드들을 같이 생성합니다. 이곳에서는 화면 편의상 두 가지 메소드만 작성하여 진행하겠습니다. 새로운 메소드들을 추가할때도 앞선 과정에서 진행된 save as example 과정을 동일하게 진행하셔서 추후 Documentation 형식으로 변환할 수 있게 설정합니다.
7. 좌측 배너 우상단의 *** 표시를 클릭하여 View Documentation 버튼을 클릭합니다. 이후 내가 작성한 요청들을 정리한 내역들이 우측 화면에 노출되면 내가 의도하여 작성한 내용이 맞는지 확인
8. 좌측에 example 형식으로 저장된 내 요청들과 example로 저장된 하위 목록들을 들어가서 살펴 본 후 우측 상단의 publish 버튼을 클릭
9. 화면은, 내가 작성한 API 들을 documentation 관련 내부 요소를 상세 설정할 수 있는 페이지로 전환됩니다. 모든 내역을 내가 의도한대로 설정하신 이후 하단의 publish 버튼을 클릭하여 최종적으로 배포를 마무리
10. Publish 된 API Documentation 관련 링크가 아래 사진과 같이 출력됩니다. 해당 링크를 클릭하여 접속
11. Postman에서 제공하는 API Documentation의 생김새는 아래와 같습니다. 이 때 주의할 점은 http 통신에 맞게 상단의 language 부분이 http로 올바르게 선택되었는지 확인하는 것 입니다. 우측 검정색 바탕의 내용을 토대로 클라이언트/프론트와 통신시 예상되는 요청 값, 기대하는 리턴 값을 상세히 확인 합니다. 모든 내역이 의도한대로 작성되었다면 배포된 해당 페이지 링크를 프론트엔드(혹은 다른 개발자)에게 공유합니다. 필요에 따라서 좌측 각 API 별로 설명 내용을 상세히 적어 다른이의 이해를 적극적으로 도울 수
12.API 문서가 Publish 된 이후에는, 7번 과정에서 “publish”로 보여지던 우측 상단 버튼이 배포 됬음을 의미하는 “published”로 바뀐 것을 확인 할 수 있습니다. 그리고 해당 버튼을 클릭하게되면 (1) 해당 페이지로 이동할 수 있는 URL 과 (2) 세부 설정내용 편집란으로 이동할 수 있는 두 옵션을 확인
'Wecode - Project 3 (부트캠프) > Project 3 과정' 카테고리의 다른 글
| Project 3 - 최종 주문/결제 api 코드 설명 (0) | 2023.10.28 |
|---|---|
| Project 3- 마지막 standing meeting (0) | 2023.10.26 |
| Project 3: [장바구니에 여러 products 담길 때], 주문/결제 api orderService.js (0) | 2023.10.24 |
| Project 3 - [주문/결제 api] 에러 핸들링 코드 및 과정 (0) | 2023.10.24 |
| Project 3 -[주문 api] unit test; test code 성공 (에러 핸들링 없이) (0) | 2023.10.22 |