Postman : API 명세서 제작 및 배포

 

여러분들은 POSTMAN 하면 어디까지 써봤나요?

저같은 경우, 초반에는 POSTMAN을 단순히 API 서버에 통신테스트를 하는 툴인줄로만 알았는데, 나중에 캐치딜 프로젝트를 하면서 알고보니 API 명세서 제작, API 테스트 자동화 등 다양한 기능을 제공해준단걸 알았습니다.

 

'언젠가는 이 글을 써야지' 를 품고 있었다가, 요새 바쁘고 적절한 상황을 찾지 못해서 글을 못써왔었는데, 이번에 마침 개인 프로젝트 중 하나를 새로 물갈이(?) 해야할 게 생겨가지고 겸사겸사 POSTMAN 활용법에 대해 글을 올리게 되었습니다.

 

 

• Postman 넌 뭐니?

 

 

앞전에 설명했다 싶이, Postman은 API 통신 테스트를 위해 많이 쓰이는 툴입니다.

단순히 저희가 요청사항에 대한 Parameter을 입력하고 'Send' 버튼만 딱 누르면 응답결과를 확인할 수 있는 편리한 툴이었습니다.

 

그런데 2016년도 쯤에 팀 간 API 명세서 공유기능, API 테스트 기능이 새로 추가되면서 개발을 더욱 편리하게 도와주는 툴이 되었습니다.

POSTMAN 다운로드 링크
https://www.postman.com/downloads/

 

 

• Postman : API 명세서 생성 및 환경변수 설정

이제 본론으로 넘어가서, API 명세서를 만들어보겠습니다.

 

1. POSTMAN 프로그램에서 좌측에 보이는 Collections를 클릭합니다.

 

 

2. 새로운 Collections(메인 폴더)를 하나 생성합니다.

저는 간단하게 아래와 같이 입력해보겠습니다.

 

 

3. 이제 제가 생성한 메인 폴더가 생성됐습니다.

 

 

4. 이제 메인 폴더에서 하위 Request를 추가해보겠습니다.

 참고  문서화 정리를 좀 더 체계적으로 하고싶으신 분은 하위 폴더를 추가 후, 하위 Request를 추가하는 방식으로 해도 좋습니다.

 

 

5. Request을 설명할 제목 및 내용을 적습니다.

 참고  description 에는 마크다운 언어가 지원됩니다.

 

6. 이제 아래와 같이 Request가 성공적으로 생성되었습니다.

 

7. 잠시 Request에 대해 상세히 편집하기 전, 잠시 환경변수를 생성해보겠습니다.

 

 

저희는 개발을 하면서 때론 개발 환경(test, development, staging, production)에 따라 서로 다른 host를 가리키며 API 테스트를 해야할 필요가 있습니다.

 

이제 소개드릴 기능이 이런 개발 환경에 따라 API Host를 서로 다른곳을 가리킬 것에 대한 설정입니다.

 

8. 저는 Test 환경에서 host라는 이름을 가진 환경변수를 아래와 같이 설정했습니다.

• INITIAL VALUE  POSTMAN 웹 API 명세서에 기록될 값

• CURRENT VALUE  POSTMAN 프로그램 내에서 host 변수에 등록될 값

 

9. 그렇게 저는 총 2개의 Environment를 추가했습니다.

참고로 저는 Production 및 Test Environment의 INITIAL VALUE 에는 Production의 host를 공통적으로 기입했습니다.

 

 

10. 다시 API 명세서를 생성하는 본론으로 돌아와서,

1. 환경변수 중 하나의 Environment를 선택합니다.
2. 그리고 아래와 같이 API Request를 진행할 Method와 URI 링크를 작성합니다.
3. URI 작성에 있어, {{host}}는 방금 저희가 설정했던 환경변수 입니다.
4. API 요청양식에 맞게 추가적으로 Parameter 작성도 합니다.

 

 참고  Parameter은 String Parameter 외에도 Headers, body 등 많이 쓰이는 파라미터가 제공됩니다.

API 서버개발자가 Parameter 양식을 받아낼 때에는, 아래 문서에 의거하여 받아내는 것을 추천합니다.

재미있는 REST API 파라미터의 종류와 개요

 

요청 준비가 됐다면, Send 버튼을 클릭해서 요청을 쏩니다.

 

11. 이제 요청 후, 아래와 같이 Response를 확인할 수 있습니다.

그리고 아래 양식을 API 명세서에 반영시키고자, Send 버튼 우측에 보이는 Save 버튼을 클릭해줍니다.

 

 

12. 하지만 저희는 단순히 Postman의 기본 기능인 Response을 확인하는게 목적이 아닌, API 명세서를 만들어 내는 것을 목표로 생각해야 합니다.

 

이어서 좌측 탭에 보이는 ▶ 버튼을 클릭해봅니다.

 

 

이어서 위에 보이는  View in web  버튼을 클릭합니다.

 

13.  View in web  버튼을 클릭하면, 아래와 같이 API가 문서화된 웹페이지로 이동되는 것을 확인할 수 있습니다!

하지만 외부인은 아직 아래 웹페이지를 접근할 수 없습니다.

 

 

14. 현재 API 명세 페이지에서 웹브라우저 상단 우측에 보이는 publish 버튼을 클릭합니다.

 

15. 외부인에게 API 명세문서를 공개하기 전, 어떻게 보여질지 설정합니다.

 참고  여기서 저는 Environment 만큼은 Production 으로 지정했습니다.

 

준비됐다면 설정페이지 하단에 보이는  Publish Collection  버튼을 클릭합니다.

 

16. 이제 공유 URI이 생성됐습니다.

아래 URI을 통해 비로그인 한 외부인도 API 명세 페이지에 접근할 수 있습니다.

 

 

17. 비로그인 사용자 포함 외부인이 접근 시, 아래와 같은 화면이 보여집니다.

 

 

• Postman : 다른 API 명세서

Postman에서는 다른 사용자가 작성한 API 명세서에 접근을 할 수 있도록 커뮤니티를 조성했습니다.

다른 사용자들은 어떻게 API 명세서 문서화를 했는지 궁금하시다면 아래 사이트를 참고해주세요 :

https://explore.postman.com/

 

 

• Postman : 과금

API 과금요소는 아래 사이트를 참고해주세요. :

https://www.postman.com/pricing/

 

저같은 경우는 개인 프로젝트라 그런지 Free Plan을 쓰면서 아직까지 별 불편한 감은 없었습니다.

 

 

 

여기까지 POSTMAN을 활용한 API 문서 제작법에 대해 알아봤습니다.

다음에는 API Request/Response Mocking 및 API 자동 테스트에 대해 알아보겠습니다.