[Postman] 쉽게 API 명세서 만들기

API 명세서를 제공하지 않는 곳이 너무 많다..

 

혼자 작업을 하더라도, API 테스트를 위해 Postman을 사용한다. 협력 작업시엔 내 생각엔 필수적으로 사용되는데 내가 여태까지 외부와 협력 할 때 API 명세를 제대로 받아서 본 적이 없다.

일반적인 프론트 개발자라면 많이 당황하게 될 것이고 API 명세서를 요청하게 될 것이다.

 

대부분 그럴 때 마다 돌아오는 답변이

 

시간도 없는데 그걸 언제 만들고 있어요.. 코드 보면서 하세요.

네에에엥...?

 

개인이 서버 테스트 할 때도 Postman 같은 툴로 테스트 하면서 진행하지 않나..? 싶지만 어쩔 수 없이 코드 보면서 분석하거나, 코드를 볼 수 없는 환경일 때는 진짜 추측해서 작업하는 경우도 잦았다.

 

물론 나중에 몰아서 API 명세서를 작업하려면 엄청난 시간이 들어가는건 사실이다.

하지만 개발을 하면서 Postman으로 테스트를 하면서 진행하면 나중에는 딸깍딸깍으로 API 명세서가 쉽게 나온다는 사실..

 

용돈벌이로 잠시 외주중에 API 명세를 요청하였는데, 결국 내가 분석해서 써야 했던 상황이 와서 포스팅을 해 본다.

 

 

Postman을 이용해서 API 명세서를 만들면 어떤 이점이 있을까?

 

Postman API Platform | Sign Up for Free

POSTMAN은 API 빌드, 테스트등을 위해 사용되는 API 플랫폼이다.

무료로 쉽게 이용이 가능하고, 환경변수 지정, 컬렉션 분리등 편리한 기능들을 많이 제공해 준다.

 

API 명세서도 쉽게 만들어 주는데, POSTMAN을 이용하여 API 명세서를 작성하게 될 경우 크게 다음과 같은 이점이 있다.

• 쉽고 빠르게 완성도 있는 명세서를 만들 수 있다.
• 각종 언어로 예제 코드를 만들어 준다.
• 응답별 Example Response를 제공해 줄 수 있어, 프론트 개발자들이 쉽게 이해하고 API를 사용 할 수 있다.

 

언어별로 바로바로 API를 요청 날릴 수 있게끔 도와준다.

 

각 응답별 Example Response를 등록 할 수 도 있다.

 

이정도면 프론트 개발자들이 감동하지 않을까

 

어떻게 API 명세서를 만들까?

 

일단 POSTMAN으로 API 테스트를 진행하다보면, 보통 그림과 같은 구조가 나오게 된다.

짧지만.. 일단 개인프로젝트 예제

 

왼쪽 위에 있는 ...을 눌러주면 View documentation 이라는 항목이 있는데,

이걸 눌러주자.

그럼 바로 API 명세가 나오게 된다.

보안등의 이슈로 특정인물에게만 공유해야 되는 API 명세서라면 Workspace를 공유하여 해당 방식으로 API 명세서를 확인하면 된다.

 

전체적으로 공유해도 되는 API 명세서라면 View documentation 으로 진입후 위쪽에 있는 Publish 버튼을 눌러주면 된다.

명세서는 이렇게 하면 나오게 되고, Publish 할 때 환경변수를 지정해 준다던가 하는 추가적인 설정을 할 수 있다.

 

Response Example의 경우에는 API 테스트 이후 나오는 결과창에서

위 Save as Example을 눌러주면 된다.

return값도 수정이 가능하고, Status code값도 수동으로 수정이 가능하다.

 

각 Response에 관한걸 넣어주자!

 

결론..

나중에 API 명세서를 직접 만들려고 하면 착잡하고 시간도 굉장히 들어가는건 맞지만, 개발과 테스트를 진행하면서 결과값들을 저장해 두면 클릭 몇번으로 쉽게 API 명세서를 만들어 줄 수 있다.

 

개발과 테스트는 어차피 해야만 하는 작업이기 때문에 저절로 나오는 API 명세서.. 꼭 이용을 해 줬으면 좋겠당 ㅎㅎ!