프로그래밍/기타

[Swagger-codegen] 협업 프로젝트를 진행할 때 Client API를 자동으로 만들어준다면 어떨까?

돌및쓰고 2020. 10. 26. 17:05

Swagger-ui

최근에는 서버와 클라이언트가 협업 프로젝트를 진행한다면 대부분 Swagger를 사용합니다.

swagger 예제프로젝트 Petstore

몇 년 전까지만 해도 서버 개발자가 API 기능과 설명을 엑셀, wiki 페이지를 직접 만들어 공유해야 했는데

이제는 API를 작성하면 자동으로 문서를 만들어주니 참 편리해진 세상입니다.

 

swagger로 인해 서버 개발자는 편리해졌지만 

클라이언트 개발자에게는 한가지 문제가 여전히 남아있습니다.

 

그건 바로

 

서버 개발자 : 서버 API 업데이트할게요~
클라이언트 개발자 : (NotFoundException, NullPointException~~) 네.. 확인했습니다.

API 업데이트로 인한 uri, 쿼리명, 변수명 변경으로 인해 클라이언트에서 NotFoundException, NullPointException를 뿜어대는 문제입니다.

 

물론 실제 현업에서는 develop브랜치로 테스트한 후에 실제 realese로 넘어가기 때문에 실제 서비스에는 영향이 없습니다. 하지만 클라이언트 개발자 입장에서는 변경점을 확인하고 수정된 클래스를 찾아 직접 변경해야 하는 수고스러운 문제가 남아있습니다.  

 

이때 서버 개발자가 변경점을 누락하거나 잘못 적어서 보내준다면...? 생각만 해도 귀찮아집니다.

 

초보 개발자인 저도 불편해하는 이런 점은

누군가 분명히 해결해 놨을 거란 생각에 조사하던 중 찾아냈습니다.

 

 

바로

Swagger-codegen

답은 가까운 곳에 있었습니다.

Swagger codegen입니다

이제 매번 변경점을 찾아다니는 일은 끝!

서버 개발자에게 일을 떠넘길 시간입니다.

 

codegen의 특징

  • 다양한 언어 지원
  • 라이브러리 형태도 지원(상단 언어별 지원현황) 무려 retrofit2 지원
  • swagger-ui링크를 통해 누구나 생성 가능

먼저 지원 언어입니다.

ActionScript, Ada, Apex, Bash, C# (.net 2.0, 3.5 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http-client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async-httpclient), Swift (2.x, 3.x, 4.x, 5.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)

 

추가로 언어별 괄호 안에 지원하는 라이브러리도 적혀있습니다.

retrofit2를 지원하는데 

감격스럽게 swagger를 토대로 다 만들어줍니다....

그리고 옵션을 통해 Rxjava형태도 가능하다고 하는 것 같습니다.

하지만 아쉽게도 kotlin-retrofit2 지원은 아직이라고 합니다.

 

swagger링크만 있다면 서버 개발자나 클라이언트 개발자나 라이브러리를 생성할 수 있는데

서버 개발자에게는 비밀로 하고 이런 게 있다고 알려줍시다...

 

사용하는 방법은 간단합니다 

git clone https://github.com/swagger-api/swagger-codegen 
cd swagger-codegen
mvn clean package
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-i https://petstore.swagger.io/v2/swagger.json \
-l java \
-o /var/tmp/php_api_client \
--library retrofit2

jar파일을 maven을 통해 빌드하고(이미 빌드된 파일로 생략가능) jar링크

generate 명령어를 통해 Client를 생성합니다.

-i swagger링크를 입력합니다 예제에서는 Json파일이지만 https://스웨거링크/api-docs 를 입력하면됩니다.

-l 생성할 프로그래밍 언어 

-o 결과물 폴더

--library 사용할 라이브러리 저는 retrofit2를 사용했습니다.

 

프로젝트 구조

구조는 api, auth, model과 Apiclient가 있습니다

api : swagger-ui에 나눠진 그룹별로 API 클래스를 생성해줍니다.

auth: swagger에 authorizations를 설정해두었을 경우에만 생성되는데 jwt 토큰 같은 값을 관리합니다

model : DTO, DAO클래스를 생성해 줍니다.

API Client의 경우는 라이브러리를 지정한 경우에만 생성되는데 클라이언트 개발자는 ApiClient객체를 통해 Api를 사용할 수 있습니다.

저는 retrofit2를 지정해 생성하였습니다.

 

이제 클라이언트 개발자는 codegen을 사용한다면 서버의 버전업마다 API를 자동으로 업데이트할 수 있습니다.

새로운 프로젝트라면 Api 뼈대를 자동으로 만들 수 있습니다.

 

하지만 API가 자동으로 업데이트된다 해서 끝나는 것은 아닙니다.

변경된 API대로 작동하도록 클라이언트 로직을 변경해야 합니다.

 

codegen을 사용함으로써 얻을 수 있는 장점은

  • DAO, DTO자동 생성, 갱신
  • API 로직을 프로젝트마다 간단하게 생성
  • 오탈자 방지
  • 변경점을 빌드 시에 바로 알 수 있다(변수명 변경 같은 경우 build시 fail)

단점이라기보단 보완점이지만 

  • 여전히 변경점을 서버 개발자가 알려주어야 함
  • Api의 네이밍을 그대로 가져옴 (생성된 class 이름의 길이가 상당합니다)
  • Api 변경점을 그대로 모두 적용하기 때문에 일부 Api만 적용할 수 없음
  • 버전마다 매번 명령어로 생성해주어야 함 (자동으로 생성하는 법은 찾아보는 중입니다)

 

아직 실제 프로젝트에 적용하기 전이지만 하루 동안 사용해보며 느낀 점입니다.

다음은 실제 프로젝트에 적용하는 내용을 가지고 돌아오겠습니다.

 

intellij에 codegen이 통합되었다는 자료있는데 AndroidStudio에는 언제 적용될지 기대되네요