Postman API 문서 만들고 Publish 해보기

안녕하세요. 이번에는 Postman(포스트맨)에 대해서 다뤄보겠습니다. 포스트맨에 대해서 간략하게 소개하자면, API Test를 조금 더 간편하고 쉽게 만들어주고 보기에도 좋게 활용할 수 있는 툴입니다. 이 포스트에서는 API 문서를 만들고 publish 해서 웹상으로도 볼 수 있게 해보겠습니다.

1. 기본 사용방법

간단하게 API EndPoint 주소, API 방식(POST,GET 등), Body 내용, Header 내용을 필요에 따라 작성하시면 됩니다.
저는 회원가입을 하는 API 대상으로 테스트해보았습니다.
response는 하단과 같이 나옵니다.

 

2. Collection 만들기 

새로운 Collection을 만들기 위해서는 탭 이동이 필요합니다. 사진의 좌측에서 Collections를 눌러줍니다. 그다음 New Collection을 클릭합니다. 저의 경우에 기존에 만들어 놓았던 API collection이 있어서 하단과 같이 뜨네요.

 

이어서 Form에 맞게 작성해주시면 됩니다. 참조하실 점은 Description을 MarkDown 형식으로 작성하실 수 있다는 점입니다. 

작성해둔 API가 있거나 1번 과정으로 빈칸을 채우면 아래 사진처럼 Save 옆 화살표를 눌러 Save As를 눌러줍니다. 그러면 내가 원하는 Collection에 원하는 이름과 설명으로 저장할 수 있습니다.

 

제가 만든 예시처럼 작성하고 저장해주시면 됩니다. Description은 임의로 작성한 것입니다. 정해진 양식이 있다면 맞춰서 작성해주시면 될 겁니다.

이제 문서작성 시 Example Response를 저장해보도록 하겠습니다. 아래 사진처럼 Save Response로 저장하면 됩니다.

 

이 과정을 거치면 아래 사진처럼 Example에 대한 naming 정하는 칸이 뜹니다.

예를 들어서 user의 profile을 조회하는 용도의 API가 있고 user/profile/3 이라는 테스트 API가 수행됐다면, "user/profile/<user_id> format" 이런 format에 맞게 작성해주시면 됩니다.

몇 개의 API를 더 작성했다고 가정하고 문서를 Publish 해보겠습니다.

3. Collection Publish 하기

먼저 아래 사진과 같이 만들어 놓은 Collection의 메뉴를 눌러줍니다. 여기서 Publish Docs를 눌러주시면 됩니다.

 

이제 웹브라우저가 뜨고, 문서 작성 전 Format을 정할 수 있습니다. 연속으로 사진을 붙여놓고 설명하겠습니다.
저는 Postman Template을 사용하기로 했습니다. 그리고 팀용으로 할 것인지 개인용으로 할 것인지도 정할 수 있습니다. 저 같은 경우 클론 프로젝트를 위한 팀이 있어서 테스트해보았습니다.
하단의 Template Summary까지 작성해주시면 완료 버튼을 누를 수 있습니다.

 

이제 완성된 템플릿의 링크가 뜹니다. 아래 화면과 같이요.

링크를 타고 넘어가면 작성한 문서가 템플릿으로 예쁘게 볼 수 있습니다.

 

4. Postman으로 Collection Import 하고 전체 테스트 수행하기

제목이 조금 장황한데, 전체 테스트를 하거나 API의 일부를 바꿔서 수행하시려면 기존의 링크 있는 창으로 가면 됩니다. 못 찾으시겠으면 Postman에서 Publish Docs를 다시 누르시면 링크가 뜹니다. 여기서 하단을 내려가시면 PUBLISHED라고 적힌 곳에 링크가 있습니다. Docs와는 또 다른데 이 링크를 클릭하시면

 

아래 사진처럼 Import를 할 수 있게 Run in Postman이 있습니다.

 

다시 한번 웹이나 Postman으로 수행하면 해당 API Collection을 가져올 수 있습니다. 저는 기존에 이미 있어서 차이가 없네요. 여기서 오른쪽으로 되어 있는 화살표를 누르면 옆에 전체 수행을 할 수 있는 칸이 뜹니다. Run을 누르면 작성한 API가 순서대로 수행됩니다.

 

환경설정을 하고 수행하실 수 있습니다. Test 해야 하는 API가 많은 경우 유용한 것 같습니다.

여기까지가 Postman을 활용한 API 정리였습니다. 계속해서 기능이 추가되고 있어서 더 유용할 것으로 예상합니다.

제가 작성한 포스트 중 역대급으로 사진이 많았네요. 더 좋은 컨텐츠로 뵙겠습니다!