배경 🐈
프로젝트를 진행하면서 API 문서 작성 툴에 대해 고민하는 시간을 가졌습니다. 처음엔 Swagger로 API 문서를 작성하고자 했으나 Postman에서 API 문서 작성을 도와주는 기능이 있다는 것을 알게 되었고, Postman으로 API 문서 작성 하는 것을 선택했습니다. Postman API를 선택하게 된 이유와 Postman으로 API 작성하는 방법에 대해 정리해보겠습니다.
Swagger 대신 Postman을 선택하게 된 이유 🤔
Swagger
- 개발자가 짠 코드 기반으로 자동으로 API 문서 생성
- 개발한 코드를 바탕으로 Swagger UI에서 API 테스트 가능
Postman
- API 문서를 먼저 작성하고 후에 그걸 보고 코드를 짜는 방식
- API 명세를 짜 놓으면 그걸로 Postman에서 바로 API 통신 테스트 가능
- Swagger와 마찬가지로 API 문서를 웹으로 게시해 팀원에게 공유 가능
선택 시 고민할 부분
- API 문서 작성 시기
- Swagger : 선 코드 작성 → 후 문서 작업
- Postman : 선 문서 작업 → 후 코드 작성
- 테스트 도구
- Swagger UI로 웹 상에서 테스트
- Postman으로 테스트
- 코드의 순수성
- Swagger : 작성 코드에 Swagger 관련 애노테이션 추가 필요
실제 코드에 Swagger 관련 코드가 들어가다 보니 순수 개발 코드를 해쳐 코드 가독성을 떨어뜨릴 수 있습니다. - Postman : 작성 코드 그대로 유지 가능
- Swagger : 작성 코드에 Swagger 관련 애노테이션 추가 필요
- API 수정 시
- Swagger : 코드만 수정하면 명세도 자동으로 수정
- Postman : 코드와 명세 모두 수정 필요
저의 경우 먼저 문서 작성을 하여 API 구성의 뼈대를 먼저 잡고 이후에 코드를 짜고 싶었고, API 통신 테스트 용도로 Postman을 사용하려고 했었기 때문에 Postman 선택하게 되었습니다. 또한 API 명세를 기준으로 내가 짠 코드가 맞는지 확인하고자 했는데, Swagger는 코드가 잘못되면 API 문서도 같이 잘못되는 구조이기 때문에 API 문서를 코드 작성의 기준으로 삼긴 힘들겠다는 생각이 들었습니다.
Postman 사용 방법
저는 이 블로그를 참고했습니다.
기존에 Postman 사용 방식과 동일하게 Http Method와 URL, Request 내용을 작성해주세요.
Response는 만든 API를 send한 다음 Save as Example을 클릭하여 하위 페이지를 생성한 뒤 Status Code와 Response Header와 Response Body를 작성하면 됩니다.
기존 Postman에서 API 통신 테스트를 하는 것처럼 명세를 작성하면 API 문서를 모두 작성하면 Collection의 ... 아이콘을 클릭하고 View documentation 버튼을 클릭하면 API 문서를 웹 페이지로 만들어서 보여줍니다. 이후 우측 상단에 있는 Publish를 클릭하면, URL이 생성되어 다른 팀원들 문서를 공유할 수 있게 됩니다.
URL 상에서는 편집은 불가능하고 읽기만 가능합니다. 만약 다른 팀원들과 API 문서를 같이 편집하고 싶으면 Postman에서 팀원을 추가하는 방식으로 가능하긴 한데, 비용이 발생하는 걸로 알고 있습니다.
