Postman으로 간단하게 API Docs 만들어보기

Postman은 보통 API을 테스트하는 목적으로 많이 사용했었는데, 요즘은 API Docs도 Postman으로 만들고 있다. 그럼 어떻게 Postman에서 API Docs를 만들 수 있는지 알아보자.

 

먼저 엄청나게 간단한 API를 만들어보겠다.

@RestController
@RequestMapping("/test")
public class TestController {
    
    @GetMapping("/v1")
    public String test() {
        return "성공";
    }
}

 

그리고 서버를 돌리고 Postman에서 왼쪽 상단에 new 버튼(빨간 박스)을 눌러준다. 

 

컬렉션을 선택한다.

 

선택했으면 자동으로 생성되는데, 이름은 간단하게 테스트라고 하겠다. 이름을 설정한 다음 아래 빨간 박스를 눌러주자.

 

요청을 추가하면 API를 테스트할 수 있는 화면이 생성된다. 여기서 우리가 만들어준 url을 입력하고 Send를 누르면 정상적으로 응답되는 것을 확인할 수 있다. 

 

여기서 오른쪽 하단에 있는 Save Response를 누르고, Save a example 버튼을 눌러서 해당 API 테스트 한 것을 저장한다.

 

저장되었다면 아래와 같이 뜰 것이다.

 

이제 거의 다왔다! 다시 한번 왼쪽 상단에 있는 new 버튼을 누르고, 이번엔 API document를 선택한다.

 

아래 사진처럼 Select an existing collection 버튼을 누르고, 아까 만들었던 컬렉션을 선택한다. 

 

그럼 이렇게 해당 컬렉션에 대한 내용을 적을 수 있는 틀이 있다. 웬만하면 적는게 좋지만, 우리는 얼른 API docs URL을 보고 싶기 때문에 넘어가도록 하겠다. 

드디어 API Docs가 만들어졌다. 팝업창을 닫지 말고 View Documentation을 눌러준다. 

 

API Docs 화면이 보이게 되는데, 아직 다른 사람들은 이 화면을 보지 못한다. 그래서 Public으로 해줌으로써 모든 사람이 볼 수 있게 설정해보자. 왼쪽 상단에 Publish를 눌러준다. 

 

그럼 아래와 같은 화면이 뜨게 되는데, 역시 빠르게 넘어가서 Publish 버튼을 눌러주도록 하겠다. 

 

드디어 모든 사람이 볼 수 있는 퍼블릭한 url을 얻었다! 확인하고 싶다면 아래 링크로 들어가보자. 

https://documenter.getpostman.com/view/18173897/2s8YsqVEsh

 

지금은 블로그로 일일이 설명을 했지만, 실제로 사용하면 1분도 안되어서 API Docs가 만들어진다. API 테스트도 하고, 바로 문서도 만들 수 있으니 개발 생산성이 올라가고, 수작업을 해야했던 귀찮음도 없어진다.