[Postman] Swagger와 차이점 및 Postman으로 API 문서 작성

기존의 Swagger를 사용한 이유는 내가 작성한 코드를 기반으로 자동으로 API를 만들어주는 부분이 너무 편해서 진행하였는데 프로젝트를 진행하다보니, 자동으로 코드를 만들어 준다는 점이 어떻게 보면 단점으로 다가 왔다. 가장 큰 문제점은 코드의 순수성을 해치는 것이 문제였다. 

 

Postman은 API 통신 테스트를 하기 위해서만 사용하는줄 알았는데, 2016년쯤 부터 Postman에서 API문서 작업을 지원한다는 것을 알게 되었고 Postman으로 API 문서 작성을 선택하였다.

 

 

Postman과 Swagger의 차이점

Swagger

• 코드를 기반으로 자동으로 API문서 생성
• 개발한 코드를 바탕으로 Swagger UI에서 API 테스트

Postmane

• API 문서를 작성 후, 코드를 작성
• API 명세서로 Postman에서 테스트 가능
• 팀원에게 공유는 가능하나, 공동 작업시 과금이 필요

고려사항

1. API 문서 작성 시기

1. Swagger : 코드 작업 후 자동으로 문서 생성
2. Postman : 문서 작업후 코드 수동으로 작성

2. 테스트 도구

• Swagger : UI로 웹 상에서 테스트
• Postman : Postman으로 테스트

3. 코드의 순수성

• Swagger : 작성된 코드에 Swagger 관련 내용 추가가 필요, 실제로 관련 코드가 들어가 있다보니 순수 개발 코드의 가독성을 떨어트림 (Postman으로 변경하게된 가장 큰 원인)
• Postmane : 작성 코드 그대로 유지, Postman에서 문서 작성

4. API 수정시

• Swagger : 코드만 수정하면 명세도 자동으로 수정
• Postman : 코드, 명세 모두 수정

 

 

API 명세서 작성

Postman에서 API 명세서 만드는 방법이기 때문에, API 통신 관련 테스트는 배제하고 진행하였다.

 

1. 우선 worksapce를 만들어준다.

워크스페이스 생성

 

2. 그럼 아래처럼 Obab이라는 워크스페이스가 만들어진다.

워크스페이스 생성 초기

 

 

3. 좌측 상단에 + 버튼을 클릭하여 Rest API Basic 템플릿을 가지고와서 진행하였다. 

API명세의 경우 프로젝트마다 다르게 진행되므로 Postman에서 제공되는 템플릿을 이용해 진행하였다.

 

REST API basics: CRUD, test & variable가 만들어지는데, 이 폴더 안에 Variavles 안에서 환경 변수 설정이 가능하다. 재대로 만들었다면 base_url이 등록되어 있을 것이다.

 

템플릿 생성 완료

 

4. 우측 상단에 메서드 별로 문서 모양이 있는데, 클릭하여 description을 수정할 수 있다.

마지막줄에 "get요청 수정해보기"를 추가하였다.

 

5. 이후 루트 디렉토리에서 View documentation을 클릭하면 전체 API를 페이지에 볼 수 있다.

view documentation 클릭

 

6. 앞서 4번에서 변경한 설명이 적용된 것을 볼 수 있다.

7. 이후 Web에 공유하기 위해 우측 상단에 보이는 Publish를 클릭하고 기본 설정을 완료 해준다. ( 아무것도 건드리지 않고 진행하였다. )

설명 수정 결과

 

8. 그럼 아래 사진처럼 URL이 나오면 저기로 접속해주면 된다.

url 리턴

 

9. URL 접속시 아래처럼 뜬다면 재대로 된것이다. 이후 이 페이지에서 테스트가 가능하다.

최종