API Documentation - PostMan

 

🌸 TIL

 

 

 

프로젝트를 하다보면 나를 위해서든 다른 개발자를 위해서든 좀 더 원활한 협업을 위해 Api Documentation이 필요하다고 느낄 때가 온다.

이번에 담당했던 프로젝트를 진행하면서 Api Documentation의 필요성을 느끼게 되었고, 아직 잘 정리된 문서가 없다는 것을 알게되었다.

 

 

(...없....으면 내가 만들면 돼!!!!! ㅎ히힣..ㅎㅎㅎ.....ㅎㅎ...........)

 

 

아직 만들어본 경험이 없어서 서툴기도 하고 완벽하진 않지만 처음부터 완벽한건 없으니까!!

 

 

 

 

---

 

 

포스트맨으로 Api Documentation 만들기

 

 

포스트맨을 사용하여 Api Documentation 만드는 방법은 조금만 구글링해도 너무 친절하게 나와있기 때문에 만드는 방법은 적지 않겠지만, 만들면서 얻은 정보들, 편리했던 점들을 몇가지만 정리해보도록 하겠다.

 

 

---

 

 💥 중복해서 들어가는 값 한번의 셋팅으로 끝내기

 

예를들어 header에 들어가는 정보나 token, params 등등 매 요청마다 공통으로 들어가는 정보가 있다면 Api를 만들 때마다 설정해주는 것은 번거로운 작업이 될 것이다.

 

심지어 request url 도 등록할 수 있다!

예를들어, 보통은 http:// ~~~~/test/1 이런 식으로 앞의 빨간 부분은 root이기 때문에 url이 공통이고 바뀌는 부분은 빨간부분의 뒤에 오는 부분일 것이다. 그러니까 이 공통인 root url까지도 설정할 수 있다!

 

 

 

 

⚙️ 설정하는 법

 

 

 

1. 포스트맨을 열어보면 상단 우측에 아래 사진과 같은 부분이 있는데, 제일 오른쪽에 있는 설정버튼을 누른다.

 

 

 

2. 그럼 다음과 같은 모달이 뜨는데 (test는 이미 한번 만든 적이 있기 때문에 한번도 만든적이 없는 경우라면 아무것도 안뜰 것이다.)

Add버튼을 클릭한다.

 

 

 

 

 

 

3. Add버튼을 클릭해서 나오는 화면에 다음과 같이 공통으로 사용될 값들을 설정해주면 된다.

모두 설정했으면 Update 버튼을 클릭한다.

 

 

 

 

 

4. 위에서 적용한 token값을 사용하려면 아래 사진처럼 {{token}} 이라고 입력만해주면 자동으로 내가 위에서 설정한 token값이 설정되는 것이다. 

 

 

 

 

 

이렇게 편한 기능이 있는줄 모르고 여태 Api 하나하나 다 설정해주느라 너무 번거로웠는데 ....

이런 편리한 기능을 제공하는 것을 보면 이런 것 말고도 정말 좋은 기능들이 훨씬 더 많을 것 같다.

 

 

마지막으로 이렇게 만든 문서를 다른 팀원들과도 공유해야 의미가 있으니 모두 접근하여 볼 수 있는 URL을 생성해보자.

 

 

 

---

 

 

💥 Publish Docs 만들기

 

 

1. 내가 만든 Collections에서 publish 할 폴더를 보면 우측에 아래와 같은 버튼이 있고, 이 버튼을 누르면 메뉴들이 나오는데 
Publish Docs를 클릭한다.

 

 

 

 

 

2. 해당 버튼을 클릭하면 창이 하나 열리고 창에 나와있는 URL이 바로 Publish Docs URL이 되는 것이다.

내 팀원들에게 이 URL을 공유해서 프로젝트의 API들을 한눈에 모아서 볼 수 있고, 상세 설명도 적을 수 있어서 편리하다.

 

또한 export해서 프로젝트 폴더 내에 import시킬 수 있는 기능도 존재한다!

 

 

 

 

---

 

마치며 🌸

 

포스트맨에 이런 편리한 기능이 많은 것을 처음 알고 좀 더 구글링하다 보니 TestCase도 생성할 수 있다고 한다.

다음 개발스터디 때에는 mocha/chai로 만든 테스트 케이스를 포스트맨으로도 시도해볼 수 있도록 연결시켜볼 계획이다!

 

내가 제안한 의견을 좋게 받아주시고 스스로 무언가를 찾아서 개선해볼 수 있도록 만들어준 회사 팀원들에게도 감사하고, 이번 계기로 좀 더 자신감을 갖고 팀원들이 편하게 일할 수 있게 부족한 점들을 찾아 해결해나가면 나에게도 팀원들에게도 모두 행복한 일이 되지 않을까 하는 생각을 하게 되었다.