Postman을 활용한 API 문서 만들기

지난번에 Swagger를 활용한 API Specification에 대한 글을 작성했었다. Swagger를 사용하여 간단하게 API 명세가 가능하다는 내용의 글이었는데, 이러한 Swagger 말고도 다른 여러 방법으로 API 문서를 만들 수 있다는 사실을 알게 되었다.

Swagger를 활용한 API Specification

Postman

나는 Postman을 지금까지 API 테스트를 진행할 때만 사용해왔다. 지난 스퍼트 프로젝트에서 처음 사용했었고, 이후에도 다른 여러 테스트를 위해 사용했었다. 자세한 사용법은 작성하지 않겠다.

Postman API Platform | Sign Up for Free

지금까지 위와 같이 여러 Collections를 만들었던 것을 확인할 수 있다. 이제 API 문서를 만들어보자!

Save as example

위와 같이 GET 방식의 테스트를 예시로 들었을 때 나는 지금까지 http://localhost:8080/api/todo/1 과 같이 직접 :tno 부분을 바꿔가며 테스트를 진행했었는데, 이러면 1이 무조건 포함되어야 하는 부분인지, TODO 번호인 tno가 들어가야 하는 부분인지 헷갈릴 수 있다.

위와 같이 http://localhost:8080/api/todo/:tno 로 수정하면 Params의 Key 부분에 자동으로 tno가 추가되는데, 옆에 Path Variables 부분의 Value를 1로 설정하였다. 추가적인 설명을 위해 Description에 "TODO 번호"라는 내용도 추가했다.
이후 우측 하단의 Save as example 버튼을 눌러 TODO 조회가 성공할 때, 실패할 때의 예시를 저장하면 성공 또는 실패할 때의 출력 결과도 명시할 수 있게 된다. Body 부분의 작성이 필요한 경우에도 위와 같이 Params 부분만 수정하면 된다.

View documentation

모든 부분에 대해 작성이 완료된 Collection에서 우클릭(혹은 우측의 점 3개 클릭)을 하고 View documentation을 선택한다. 그러면 아래와 같이 문서 내용이 보일텐데, 나는 이미 남은 과정까지 완료했기 때문에 우측 상단에 초록색으로 Published라고 뜨지만 처음 하게 된다면 우측 상단에 회색으로 Publish라고 뜰 것이다.

해당 버튼을 누른 후에 어떤 웹사이트로 이동한 후, 나머지 정보를 입력하게 되면 다음과 같이 문서를 확인할 수 있는 링크가 뜨게 된다.

TodoApi

해당 링크로 들어가게 된다면 아래와 같이 문서를 확인할 수 있다.

---

결론

오늘은 Postman으로 작성하는 간단한 API 문서에 대해 알아보았다. 일단 Swagger와 비교해본다면 각각 장단점이 있는 것 같다. 아래는 Swagger를 사용했을 때 사용할 수 있는 기능의 예시인 Try it out이다.

Swagger는 코드 자체에 명세 내용을 입력하면서 코드가 지저분해보이지만 위의 Try it out 기능을 통해 tno를 바꿔가며 간단하게 직접 테스트해볼 수 있다는 장점이 있다.

반면 Postman을 활용한 API 문서는 코드에 어떤 내용과 라이브러리를 추가할 필요가 없으며 서버를 실행하지 않을 때에도 다른 사람들이 해당 문서를 읽을 수 있다는 장점이 있지만 위와 같은 기능을 사용하기 위해 Postman 설치가 필요하며, 내용도 Swagger에 비해 턱없이 부족한 듯 보인다.

하지만 대부분의 테스트를 Postman으로 하기 때문에 테스트를 진행하면서 동시에 API 문서를 작성할 수 있다는 장점도 보여서 앞으로 Postman을 자주 애용할 것 같다는 생각이 들었다.

장단점을 비교해가면서 내가 사용하는 것을 사용하는 이유를 명확히 해야 한다는 것은 앞으로 정말 중요할 것이라는 생각이 들어서  추가적으로 Spring REST Docs에 대해서도 공부하고 있었는데 진입장벽이 생각보다 높은 것 같아서 시간이 좀 걸릴 것 같다는 생각이 들어서 일단 후순위로 미뤄놓고 다른 일을 먼저 할 것 같다. 계속 열심히 하자..