인텔리제이(Intellij) HTTP 파일을 통한 API 관리와 고민.

현 회사에서 외부와 통신할때 사용하는 인터페이서 정의서 다른말로 하면 API 스펙 정의서가 존재한다.
그러나 실질적으로 개발자들의 경우 각자의 컴퓨터에서 Postman을 통하여 별도로 관리하고 테스트하는 경우가 많다고 이부분에 대해서 통합관리를 하고싶다고 어떻게 관리하면 좋을지 의견을 물어보셨다.(부장님)

문제점

현재 사내에서 따로 관리하는게 없다보니 실질적으로 신입 개발자가 회사에 와서 API를 호출해야하거나 스펙을 확인하고자 할 때는 다음과 같이 해야한다.

1번 방법
어디있는지 알기도 힘든 인터페이스 정의서를 찾아서 해당 문서에 적힌 스펙을 확인 후 요청을 만들어 테스트한다.

2번 방법
로컬환경에서 API 프로젝트를 열어서 어떻게 동작하는지 확인을 해야한다.(컨트롤러와 서비스 확인 및 요청정보  확인 등)

그래서 관리를 위해 다음과 같은 방안들을 생각했었다.

1번 방법

Postman에서 제공하는 유료서비스를 이용하는 것이였다.

장점
Team단위로 관리 할 수 있고, 권한 관리 및 글로벌 변수를 사용하는 형태로도 가능하다.

단점
3명 이상인 경우 구독하는 형태로 가격에 대한 지불이 필요하고, 실질적인 정보들이 해당 회사의 db쪽에서 관리가 된다.
가격의 경우 한달 단위의 경우 1명당 14달러. 1년 단위인 경우 19달러 정도로 싼건 아니였다.
상세내용은 아래 페이지에서 확인이 가능하다.

Plans & Pricing | Postman API Platform

Plans & Pricing | Postman API Platform

 

API통신을 하는 경우 별도의 KEY를 관리하게 되는데 이 부분들을 글로벌 변수에 관리하거나 한다고 하면 해당 정보들이 모두 노출이 되는 형태가 되어버린다.... 고민했지만 포기.

2번 방법

현 회사는 개발자 누가 들어오든 인텔리제이 라이센스를 1년 단위로 구매하여 사용하고 있다. 이에 따라서 인텔리제이에서 제공하는 Http Client 플러그인의 기능을 사용하면 어떨까 했다.

장점
별도의 설치가 필요하지 않고, 실질적인 개발 소스상에서 확인 및 요청이 바로 가능하다.
또한 git이나 svn을 사용하는경우 수정하고 형상관리를 통해 이력조회 및 관리가 가능하다.
무료다.
글로벌 변수로써 사용하는 부분도 POSTMAN과 동일하게 제공한다.
GIT, SVN 서버가 별도 운영중이라면 사내에서 보관 및 관리된다.(KEY값 등등.)

단점
별도의 관리 파일이 늘어난다.
만약 변동이 있는 변수값을 사용하는 경우에는 형상관리 프로그램에 의해 수정한 부분들이 계속 commit을 원하는지에 대한 부분이 요청 될 것이다.
HTTP파일 내부에서 보여지는 모습이 요청정보가 많은경우 보기 힘들다....

 

예를들면 다음과 같이 주석으로 해당 API스펙에 대해서 표기하고 싶었는데 주석만해도 이미 한페이지를 차지해버렸다.

 

결론

결론적으론 아직 사내에서 어떤식으로 관리하자고 정해진건 없다.
POSTMAN으로 관리하든 인텔리제이에서 제공하는 HTTP를 사용하든 어떤걸 선택하더라도 담당자(누군가는) 인터페이스가 변경이 되면 문서와 스펙을 모두 수정하고 관리해야만 한다...
이제 그 관리를 어떤식으로 하면 좋을지에 대해서 고민이 되야하는게 아닌가 싶다.

 

기타

회사내에서 Swagger나 RestDocs를 이미 적용하여 사용하고 있는 경우에는 다음과 같은 방법도 괜찮을것 같다.
RestDocs도 그렇고 인텔리제이에서 제공하는 HTTP도 그렇고 좀 괜찮은 UI가 있으면 어떨까 하는 생각을 가끔 한다.
다음과 같이 2개를 엮어서 사용하는 방법도 가능하다고 하니... 이미 RestDocs나 Swagger가 적용되어있다면 추가적인 작업이 적을 수 있으니 아래 방법으로 관리를 시도했을것 같다. ㅠ

RestDocs와 Swagger 그리고 Open API 3 를 사용한 방법도 있다.

Spring Rest Docs & OAS 의 필요성 | DEZANG.net

Spring Rest Docs & OAS 의 필요성 | DEZANG.net

Spring Rest Docs & OAS - 시작하기 | DEZANG.net

Spring Rest Docs & OAS - 시작하기 | DEZANG.net

spring Rest Docs + Swagger UI로 MSA 환경에서 API 문서 통합 관리하기

spring Rest Docs + Swagger UI로 MSA 환경에서 API 문서 통합 관리하기

OpenAPI Specification을 이용한 더욱 효과적인 API 문서화 | 카카오페이 기술 블로그

OpenAPI Specification을 이용한 더욱 효과적인 API 문서화 | 카카오페이 기술 블로그

Swagger와 Spring Restdocs의 우아한 조합 (by OpenAPI Spec)

Swagger와 Spring Restdocs의 우아한 조합 (by OpenAPI Spec)

 

참고주소

아래에는 잘 정리된 블로그 글이 있다. 이미 2018년도때 업데이트되고 얼마안된 시점부터 잘 사용하던 사람이 많다.

아직도 postman 쓰세요? Intellij http를 통해 api를 테스트해보자!

아직도 postman 쓰세요? Intellij http를 통해 api를 테스트해보자!

IntelliJ의 .http를 사용해 Postman 대체하기

IntelliJ의 .http를 사용해 Postman 대체하기

IntelliJ http Client 응답값 변수로 저장하고 사용하기

IntelliJ http Client 응답값 변수로 저장하고 사용하기

 

HTTP Request로 postman 대체하는 이유 및 기타 설명

[IntelliJ] HTTP Client 사용하기 : Postman 대체하기

[IntelliJ] HTTP Client 사용하기 : Postman 대체하기