Postman으로 Rest API 문서화하기

API 를 왜 문서화할까?

고객이 API 를 사용할 때 API를 이해하고, 사용할 수 있도록 API 를 문서화작업을 해주어야한다.

 

---

 

postman을 사용해서 API 를 문서화하기 ( 기본 )

1. Postman에서 Collections 로 들어간다.

 

2. New를 클릭해서, API 이름을 작성해준다.

 

3. 만든 API 의 오른쪽 마우스를 클릭해, New Request 를 만들어준다.

어떤 호출인지 작성하는 용도인듯

 

4. 어떤 호출인지 이름을 작성해주고, API 주소를 입력해서 Save 해준다.

 

5. 사용하는 사람이 예제를 볼 수 있도록 Save as example 을 클릭해준다.

 

---

 

path value가 들어가야할 경우

 

1. API에 :id를 추가하면, 아래에 Path Variables 에 id 가 추가된다.

아래에 Path Variables 를 확인

 

2. id 옆에 value에 값을 입력하고 send를 클릭하면, 그 id값으로 데이터가 조회된다.

 

---

 

Query Params가 들어갈 경우

 

1. 똑같이 query 를 넣어주되, 값만 빈 값으로 설정해놓으면 된다.

 

2. 아래에 생성 된 query 옆 value 자리에 값을 입력하면 자동으로 주소에 작성되는 걸 확인할 수 있다.

 

---

 

localhost 가 아닌, 다른 이름으로 수정하기

 

1. 글로벌 변수 생성하기

1. 아래와 같은 눈 모양을 클릭한다.

 

2. Environment 부분에서 Add 를 해준다.

 

3. 아래와 같이 작성한다. (로컬 서버를 생성)

 

4. Globals 부분도 Add 해서 같게 작성해준다.

 

 두개 다 Save 해줘야한다.

개발 서버 (로컬) : 서버 개발자가 안정적으로 작업할 수 있는 서버
dev 서버 : 클라이언트 개발자가 안정적으로 작업할 수 있는 서버
실서버 : 실제 사용자들이 안정적으로 서비스를 이용할 수 있는 서버

 

5. No Environment 로 바꿔, new Environment 를 추가해준다. (실서버 생성)

 

6. 실서버의 initial value 값을 아무 주소로 바꿔본다. ( 원래는 배포된 API URL 을 넣어야함 )

 

2.  글로벌 변수 사용하기

 

1. 아래와 같이 {{}} 안에 만들어놓은 변수를 입력하면 호출이 된다.

 

2. 로컬 서버와, 실 서버를 번갈아가면서 차이를 본다.

왼쪽이 로컬, 오른쪽은 실서버

 

3. 만들어놨던 문서에 변수로 바꿔넣어준다.

 

---

 

문서화한 API Export 하기

 

1. 명언 API 의 오른쪽 마우스를 클릭하고 Export 를 누른다.

 

2. JSON 파일로 저장한다.