[Postman] 포스트맨을 이용하여 API 명세서 작성하기

서론

이번 글에서는 포스트맨을 이용하여 API 명세서 작성을 하는 법을 다뤄보고자 한다. API 명세서는 호출할 API 이름, 데이터 전달 형식, 파라미터, 반환 값 등의 정보들을 정확하게 기술하여 API의 결과를 명확히 해석하기 위해서 API 설계 시 반드시 필요하다.

 

예전에는 문서 형식으로 API를 명세화하여 필요한 사람들에게 제공하곤 했지만 요즘에는 YAML, XML 등과 같이 컴퓨터가 해석하기에도 용이한 형식으로 많이 발전되었다. 뿐만 아니라 이번 글에서 다룰 포스트맨과 같이 여러 툴을 이용해서도 API 명세서를 쉽게 작성할 수 있다.

 

 

포스트맨을 처음 사용하는 분들은 여기를 참고하면 좋을 것 같다. 해당 글에서는 포스트맨 설치 방법과 node.js를 이용하여 포스트맨을 사용해보는 예제를 다루고 있다. 따라서 이번 글에서는 포스트맨이 설치되어 있다는 가정 하에 진행된다.

컬렉션(Collection) 생성하기

포스트맨에서 컬렉션은 프로젝트 단위라고 쉽게 생각할 수 있다. 언뜻 보면 문서의 형태를 띠고 있지만 컬렉션 안에 또다른 문서들이 존재할 수 있기 때문에 컬렉션은 하나의 프로젝트라고 생각하면 된다. 이제 컬렉션을 생성하는 방법을 알아보자.

먼저 포스트맨에 접속하면 위 사진과 같은 탭이 있을 것이다. 컬렉션을 생성하는 방법은 두가지이다.

New 버튼 클릭 후 Collection 클릭하기

New 버튼을 클릭하면 위와 같이 메뉴가 나온다. 여기서 Collection을 눌러 생성할 수 있다.

화면에 보이는 Create Collection 버튼 누르기

위의 Create Collection 버튼을 통해서도 컬렉션을 생성할 수 있다.

필자는 컬렉션을 생성하고 컬렉션명을 Test로 설정했다.

API Request 추가하기

이제 본격적으로 API 명세서를 작성할 차례이다. 명세서를 작성하기 위해서는 API Request를 추가해야 한다. 추가 방법은 다음과 같다.

화면에 보이는 Add a request 글씨 클릭하기

··· 탭 누른 후 Add request 버튼 클릭하기

Request 구체화하기

필자는 생성한 Request의 이름을 유저 정보 조회로 지정했고 요청 메소드는 GET 그리고 요청 경로는 localhost:3000/user로 지정했다.

실제 서비스에서 사용하는 메소드와 요청 경로를 작성하고 Request 이름은 이해관계자들이 이해할 수 있도록 적절하게 작성하면 된다.

 

그리고 위 사진의 오른쪽 공간을 보면 Documentation 부분이 보이는데 저 부분에는 해당 Request가 어떤 역할을 수행하는지 설명하는 부분이다. (Markdown Language 를 지원한다.)

 

필자는 Documentation에 모든 유저의 정보를 가져오는 API라고 작성했다. (작성 후 반드시 저장해야 한다)

이제 정의한 경로로 Request 요청을 보내고 Response를 받아보자.

요청 보내기 및 응답 받기

해당 경로에 Send를 하면 필자는 아래와 같은 응답을 얻는다. 이제 응답 결과를 저장하기 위해 먼저 Ctrl + S로 Save를 한 뒤에 위 사진과 같이 Save Response버튼을 클릭하고 Save as example을 클릭한다.

Example 확인하기

컬렉션 구조를 보면 Request 하위에 유저 정보 조회이름의 Example이 생성된 것을 확인할 수 있다. 그리고 그 안을 보면 요청 경로, 파라미터, 헤더, 바디 정보, Status code 등이 어떻게 구성되었는지 확인할 수 있으며 응답 결과는 어떻게 나오는지 알 수 있다.

컬렉션 문서화하기 (추출하기)

이제 사용자 요구에 맞게 정리된 컬렉션을 문서화하여 외부에서 접근할 수 있도록 하고자 한다.

먼저 New 버튼 클릭 후 API Documentation을 클릭한다.

그러면 위와 같은 메뉴가 나오는데 Select an existing collection 클릭 후 우리가 만든 Test 컬렉션을 클릭한다.

추출하기 전에 해당 컬렉션이 어떤 내용인지 Description을 작성할 수 있으나 필자는 따로 건드리지 않고 Save를 눌러 저장했다.

저장이 되었으면 View Documentation을 눌러 Test 컬렉션이 문서화된 곳으로 이동하자.

외부에 API 명세서 공개하기

생성된 문서를 보면 사진과 같이 우측 상단에 Publish라는 버튼이 있다. 해당 버튼을 누르면 API 명세서를 외부로 공개하기 위한 설정을 진행할 수 있다.

이런 식으로 구성된 페이지가 열린다. 여기서 API 명세서 페이지를 사용자 요구사항에 맞게 커스텀 할 수 있다. 필자는 따로 건드리지 않고 Publish를 클릭했다.

API 명세서 사이트 확인하기

Publish가 끝나면 위와 같은 페이지로 이동한다. 위 사진과 같이 나오면 API 명세서를 외부로 공개할 수 있게 된다. 위에 보이는 링크를 통해 API가 명세된 컬렉션으로 이동할 수 있다. 또한, Unpublish 버튼을 누르면 외부 공개를 다시 막을수도 있다.

 

이제 위 링크를 통해 접속해보았다.

우리가 작성한 컬렉션이 외부로 잘 공개된 것을 확인할 수 있다.

결론

이번 포스팅 글에서는 간단하게 포스트맨에서 API 명세서를 작성하는 법을 다루고자 GET 메소드 하나를 예시로 들었다. 그러나, 실제 프로젝트에서는 여러 메소드가 존재하고 Headers, Body를 사용하는 경우도 많다. 따라서 직접 POST, PUT, DELETE등의 여러 메소드 예시도 작성해보면서 API 명세서를 작성하는 연습을 해보면 도움이 많이 될 것 같다.

---

출처

• https://docs.microsoft.com/ko-kr/connectors/custom-connectors/create-postman-collection
• https://velog.io/@jinee/TIL-Postman%EC%9C%BC%EB%A1%9C-API%EB%AC%B8%EC%84%9C-%EB%A7%8C%EB%93%A4%EA%B8%B0-l4k5mj31rl