[Document] API 명세서 툴 비교

 

API 명세서 툴 비교

 

✅ 들어가기에 앞서

회사 내부에 따로 프론트를 담당하는 분이 없어서 백엔드 개발자가 API를 만들고 JSP에 사용하는 방식이었다.

외부에 명세서를 제공할 때는 엑셀 또는 PPT로 전달했다.

이러한 방식 때문에 명세서 작성 및 템플릿을 중요하지 않게 생각했던 것 같다.

 

이번에 프론트 기술을 JSP에서 Vue.js를 변환하기로 하면서

프론트 개발자와 외부 고객사에 제공하는 API 명세서 툴을 찾고 회의한 결과를 작성하려고 한다.

 

✅ 명세서 툴(Tools) 

※ 개인적인 생각을 기반으로 작성했습니다.

 

1️⃣ Swagger

라이브러리를 설치해서 사용하는 방법이 swagger 회사가 제공하는 라이브러리인지는 모르겠다. 

swagger 디자인을 기반으로 하고 있는 오픈 소스이지 않을까 하는 개인 생각이다.

• 장점
  • 코드와 명세서를 하나의 파일에 관리할 수 있다.
  • 애플리케이션이 동작하면 내부 서버 ip로 웹에서 템플릿을 열 수 있다.
• 단점
  • 코드보다 명세서 작성을 위한 코드가 길어지고 가독성을 해친다.
  • API 테스트와 명세서 작성을 따로 작업해야한다.

2️⃣ Postman

사이트: https://www.postman.com/

• 장점
  • 작성한 API를 테스트하면서 바로 명세서로 만들 수 있다.
  • 괜찮은 디자인의 템플릿을 제공해주고 있다.
• 단점
  • 회사 단위로 사용하기에는 가격이 너무 비싸다.
  • API 명세서를 HTML 파일로 제공하고 있는 것 같지는 않다.

3️⃣ Insomnia

사이트: https://insomnia.rest/

• 장점
  • 작성한 API를 테스트하면서 바로 명세서로 만들 수 있다.
  • 단 하나의 프로젝트에만 참여하는 인원수 제한이 없다.
  • 오픈 소스를 통해 템플릿을 만들 수 있다.
• 단점
  • 포스트맨에 익숙해져있어서 잘 사용하기 위해 시간이 소요된다.
  • 포스트맨만큼 많은 기능을 제공해주는 것 같지는 않다.

✅ 결론

3개의 툴 중에서 Insomnia를 사용하기로 결정했다.

결정하는 과정이 다소 힘들고 시간이 걸렸지만 API 명세서 기반을 다질 수 있어 좋았다.