[Postman] Mock Server / API Documentation 만들기

예전부터 postman을 사용하여 만든 api를 호출하고 테스트 해왔는데 생각보다 기능들이 많고 손쉽게 만들 수 있어서 아래와 같이 정리를 합니다. 여기서 설명할 내용은 mock server와 api 문서를 만드는 방법입니다. mock server를 만들면서 api 문서화를 같이 진행할 수 있고 그 반대의 경우도 가능하므로 개발자에게 아주 편리한 기능을 제공합니다.

1. Mock server 생성하기

이미지의 좌측 상단에 있는 New 버튼을 누르면 팝업이 뜨는데 여기서 Mock Server를 눌러줍니다. 

누르면 다음 화면이 위와 같이 나오는데 Request Path 부분에 경로를 입력하면 우측 하단의 Next가 활성화가 됩니다. 위에서 지정한 Request Path는 나중에 수정이 가능하므로 일단 test라는 경로로 지정하고 다음으로 넘어갑니다.

Mock server의 이름을 지정해주면 위 경우와 마찬가지로 우측 하단의 Create 버튼이 활성화가 됩니다. 이름은 역시 나중에 수정이 가능하므로 Test mock server로 임시 지정해 줍니다. 여기서는 설명하지 않지만 만약 이미 존재하는 Collection에 Mock Server를 추가하는 경우라면 Name 아래의 Use an environmnet에서 선택하면 됩니다. 없을 경우 위와 같이 아무 것도 선택하지 않으면 됩니다.

Create를 누르면 위처럼 Mock Server가 생성됩니다. 빨간색 박스로 가린 부분에 생성된 Mock Server URL이 발급됩니다.

위와 같이 Mock Server만 생성하면 Collection이 같이 만들어 집니다. 여기서 한 가지 확인해야 되는 부분은 {{url}}은 postman의 환경 변수를 타기 때문에 우측 상단에 있는 No Environment 상태에서 호출하면 호출이 되지 않습니다.

위처럼 생성한 Test mock server를 설정해야 위에서 생성된 mock server url이 {{url}} 변수에 연결됩니다.

2. mock api 반환 형태 설정하기

위의 /test/ api가 호출됐을 때 어떤 response를 줄지 구성해야 하기 때문에 우측 상단쪽에 있는 Examples에서 Default를 누릅니다.

위와 같이 아래쪽 EXAMPLE RESPONSE를 원하는 대로 꾸며줍니다. 

저장을 한 다음, 해당 API를 호출하면 설정한 대로 나오는 것을 확인할 수 있습니다.

3. API 문서 만들기

/test/ API의 request와 respoonse에 대한 설명 뿐만 아니라 해당 collection에 대한 설명을 작성할 수 있습니다. postman은 markdown 문법을 지원하므로 테이블 형태로 작성하는 것이 아니라면 손쉽게 꾸밀 수 있습니다.

문서를 추가하고자 하는 api 목록에서 오른쪽 마우스 또는 우측 ... 을 클릭하여 Edit을 눌러줍니다.

위와 같이 설명을 추가한 다음 Update를 누릅니다.

생성한 API 문서를 확인하기 위해 Test mock server 리스트에 마우스를 올려놓으면 화살표가 보이는데 해당 화살표를 누른 다음 View in web버튼을 누릅니다.

그러면 위와 같이 웹이 호출되고 위와 같이 작성한 API 문서를 확인할 수 있습니다.

요약

위와 같은 방법으로 손쉽게 API 문서와 Mock server를 생성하고 모니터링이나 변경로그 기능도 제공합니다. 또한 하나의 collection에 여러 mock server url을 가질 수 있고, 환경변수를 사용하여 mock server 별로 파라미터를 다르게 지정할 수도 있습니다. 무료 버전에서는 생성할 수 있는 collection과 request 등이 제한되어 있지만 유료 버전이 비싼 편에 속하지 않기 때문에 협업 도구로 충분히 고려할 만합니다.

장점

• Mock Server를 위한 서버 구성이 필요가 없음
• 특별한 코딩이 필요 없고 단순한 클릭 몇 번으로 손쉽게 생성 가능
• 또한 API 문서도 쉽게 생성 가능
• 환경 별로 변수의 값을 다르게 설정할 수 있음
• CORS가 설정되어 있음

단점

• 호출 횟수에 제한이 있음 (1분당 60회)
• 특정 API의 Example에 Path, Header, Params, Body가 같은 것이 있으면 최근에 추가된 Example가 호출됨
  
  • 하지만 경로, 헤더 파라미터, 바디가 각각 다르게 설정할 수 있다는 장점이 있음