[Postman] API 문서 만들기

Postman 은 API 테스트를 위해 가장 많이 사용되는 툴이다.

나도 항상 웹 API 개발 시에는 항상 Postman을 사용해서 API 테스트를 했었는데,
이번에 Postman에 API 문서를 작성하는 기능이 있다는 사실을 알게되었다.

Postman으로 API 문서를 작성하게되면, API를 테스트함과 동시에 API 문서도 같이 작성할 수 있다는 장점이 있다.

이제 Postman으로 API 문서를 작성하는 방법에 대해 알아보자

 

먼저 API 문서를 만들기 위해 테스트 API 를 생성해보자

1. workspace 생성

- 말그대로 '작업 공간'을 의미한다.
-Visibility 옵션을 선택해서 해당 workspace에 접근할 수 있는 사용자를 제한할 수 있다.

2. Collection 생성

- Collection은 Request(요청) 들을 저장하기 위한 컨테이너 또는 폴더며, 간단히 말하면 요청들의 집합을 의미한다.
- 'New' > 'Collection' 을 선택하여 Collection을 생성할 수 있고, 간단히 좌측의 Collections 옆의 '+' 버튼을 클릭해서 생성할 수도 있다.

3. Request 생성

- 위에서 생성한 Collection 아래에 Request를 생성한다.
- '...' 클릭 > 'Add request' 를 클릭해서 생성할 수 있다.

3-1. Request 작성

- 해당 Request에 대해 url, parameters를 작성한 후, 'Send' 버튼을 클릭하면 해당 API가 호출되며, 아래에 Response(응답)값이 출력되게 된다.
- 이 때, 우측의 'Save Response' > 'Save as example' 을 클릭해서 이 API의 example도 저장할 수 있다.

4. API 문서 생성

- workspace에서 'New' 버튼 클릭 > 'API Documentation' 을 선택 후 위에서 만든 Collection을 선택한다.

- Markdown 문법으로 Collection에 대한 설명을 추가한 뒤 'Save' 버튼을 클릭하면,

- 아래와 같이 API 문서가 생성된다.

 

4-1. API 문서 공유

- 이 API 문서를 웹 URL을 통해 조회 가능하게 하기 위해 우측의 'Publish' 버튼을 클릭한다.

- Publish를 위한 여러가지 설정 들을 완료한 후 (따로 작성하지 않아도 상관은 없다) 아래의 'Publish' 버튼을 클릭하면,

- 이렇게 URL이 출력되며, 이제 이 URL을 통해 내가 생성한 API 문서를 조회할 수 있게 된다.