API Docs에대해 처음 알았을때 swagger를 사용해서 만들었다.
그런데 최근에 Postman으로도 가능하다는걸 알았다.
어떻게 하는지 궁금해서 해봤다.
Postman
API 개발 및 테스트를 위한 협업 도구로서, 주로 개발자들이 API를 효과적으로 테스트하고 관리하는 데 사용되는 도구이다.
Postman을 사용하여 API 엔드포인트에 요청을 보내고 응답을 검사하여 API를 효과적으로 테스트할 수 있다.
API Documentation
API Documentation이란 백엔드에서 생성한 API의 구성요소들을 개발자들끼리 어떻게 주고받을지를 문서화한것을 말한다.
API를 문서화하면 정보들을 효율적으로 공유할 수 있어 개발자가 직접적으로 소통해야하는 빈도를 줄이고, 일의 능률을 높일 수 있다.
API 문서에는 문서의 목적과 의도, 엔드포인트 / API별 필수 인자 등에 대한 세부 정보가, 개발자는 물론 일반 사용자 까지 모두 이해하기 쉬운 형식으로 구조화되어있다.
이는 사용자(내코드를 보는 사람)로 하여금 다양한 요청-응답 방식을 더 잘 이해할 수 있도록 도와줄 수 있어, 문서를 작성하는데 소비한 시간 이후의 비용은 최소화시켜준다.
1. 구성 요소
API 문서는 내가 만든 API로 작업하는데 필요한 모든 정보가 포함된 메뉴얼이다.
필수적으로 들어가야하는 요소들은 아래와같다.
- 해당 API의 사용 예시
- URI (엔드포인트)
- 샘플 request 양식
- request 파라미터
- 샘플 response 양식
- response 파라미터
- 에러 핸들링 정보
2. API 문서화 Tools
API를 문서화해주는 외부 도구는 여러가지가 있다.
ex) ReDoc.ly, SwaggerHUB, Stoplight, ReadMe, Postman, LucyBot, DocGen, DapperDox, WidderShins
가장 많이 본것은 swagger와 postman이다.
Postman으로 API DOCs 만들기
1. postman 앱을 실행한 후 메인 홈 화면에서 좌측 Workspace 란을 확인한다.
2. new를 눌러 새로운 워크 스페이스를생성한다. 워크스페이스의 명은 프로젝트명이나 팀이름으로 작성한다.
3. 생성된 워크스페이스의 좌측 Collection 부분의 + 버튼을 클릭하여, 새로운 API Collection (모음집)을 만든다.
이후 소속된 프로젝트와 동일한 명칭등, 팀원들끼리 사용 하기에 적절한 Collection 명칭을 지어 준다.
4.새로운 Collection 페이지 내부 좌측 배너에서 새로운 http request를 생성한다.
5. http 메소드를 설정하고 원하는 URI를 주소란에 치면 내가 의도한 통신 요청을 보낼 수 있다.
요청이 성공하면 아래와 같이 반환된 결과값도 확인할 수 있다.
반환된 결과값을 save as example을 눌러 저장해준다.
6. 생성한 콜렉션의 ... 의 view documentation을 클릭하면 example 형식으로 저장된 요청들이 문서화되서 나타난다.
7. 우측상단의 publish를 클릭하면 배포하는 페이지로 이동하고 publish를 눌렀을때 API 문서와 관련된 링크가 생성된다.
8. 생성된 링크로 접속하면 만들어진 문서를 확인할 수 있다.
9. 다시 콜렉션의 view Document를 눌러보면 published라며 배포되었다고 표시가뜬다.
정말 편리한데..?