Postman?

Postman은 개발한 API를 테스트하기 위해 사용하는 플랫폼으로 유명하다.
많은 사람들이 이용하는 플랫폼인 만큼 다양한 기능들을 제공하고 있다. 그 중에서도 오늘은 Postman을 통해 API Documentation을 만들어 보는 것을 소개해 보고자 한다.

나는 그동안 API 문서를 구글 스프레드시트를 이용해 작성하곤 했으나, 서버가 수정될때 마다 해당 문서를 동기화 시키는 일이 쉽지 않았다. 그로 인해 생기는 문제점들이 지속되어 API 문서 동기화 되는 플랫폼을 찾아 나섰다.

평소 API를 개발하면서 정말 많이 사용하고 애용하는 Postman을 테스트하는 기능으로만 사용하고 있었다. 그러던 중 👉Postman에 API 문서 작성을 위한 기능이 있다는 사실!!👈을 알아버렸고 바로 적용을 해버렸다. (~그동안 만들어둔 API문서를 옮겨 오는게 매우 귀찮지만~)

시작하기 앞서

본 포스팅에서는 포스트맨 설치 방법 및 Request 보내는 방법 등이 설명 되어 있지 않습니다.
더불어, 잘못 설명된 부분이 있다면 주저없이 피드백 해주세요!!!

---

1. Collection 생성

우선, Collection을 생성해야 한다. Collection은 Request들의 폴더 역할을 한다.

Postman실행 -> New -> Collection

Collection의 이름과 설명 등을 채워 생성한다.

2. Request를 생성한다

생성한 Collection 이름 -> Add Request

Request 이름과 설명(마크다운 문법을 제공 한다)을 채우고 생성할 Request가 들어갈 폴더(Collection)을 지정한다.

3. Request 보내기, Respond 저장하기

test 할 API의 URI, Header, Body값 등을 채워 Request를 보낸 뒤
Send 옆 Save를 눌러 저장한다.

Respond 받은 값을 저장하기 위해 Save as example을 눌러준다.

Respond 받은 데이터의 이름을 지정해 준 뒤, Status 값을 확인 한 후 저장 한다.

4. API 문서 뽑기(?)

New -> Documentation을 선택해 API 문서를 뽑아 확인한다.

문서화 할 Collection을 선택 -> Next

마크다운 문법으로 Collection 설명을 보충한 뒤 -> Next

드디어!! API 문서를 확인 할 수 있는 웹 링크가 나온다.

5. API 문서 확인하기

위 과정을 통해 받은 링크를 타고 들어가 보면 아래와 같이 API 문서가 생성된 걸 확인 할 수 있다.

위에 있는 사진은 간단한 API에 대한 문서라 아래 문서를 통해 설명을 조금 보태 보려 한다.

• 마크다운으로 작성한 Collection에 대한 정보는 아래와 같이 확인 볼 수 있다.
• API 테스트를 위해 넣은 Header와 Body도 확인 할 수 있다.

더불어, 여러 Response를 저장해 아래 이미지처럼 드롭 다운 메뉴를 통해 다른 응답 결과도 확인 할 수 있다. (따라서, 하나의 요청에 대한 여러 가지 응답 결과를 저장할때 각 응답들의 이름을 다르게 하자!!)

오늘은 이렇게 Postman을 통해 API 문서를 작성하는 방법에 대하여 포스팅 해보았다.
~🙌이제 포스트맨 응답 결과 하나하나 복붙하는 일에서 해방이다 우헤헤 ~!!🙌~

원래는 API 문서 동기화를 위해 Swagger를 사용할 생각이였는데 Spring만 동기화 된다는 단점을 발견 했다. 나는 Nodejs와 Express로 개발하고 있는 프로젝트에 적용할 예정이였기에 Postman API Documentation을 선택했다.

Postman을 애용한다면 test하면서 api 문서를 만들 수 있으니 꼭 한번 적용해 보길 추천한다.
~복붙의 지옥에서 벗어나고 건망증에 의한 클라이언트 친구들에게 피해를 덜 줄 수 있답니다 😇 (본인 이야기) ㅎㅅㅎ~