Open Api Generator를 Android 프로젝트에 적용하기

개발을 하다 보면, API DTO에 변경에 어려움을 겪을 때가 있습니다. 우리가 흔히 사용하게 되는 REST API의 통신을 좀 더 간편하고 효율적으로 할 수 있는 방법 중 하나가 바로 Open API Generator입니다. 오늘은 OpenAPI Generator를 Android 프로젝트에 어떻게 적용할 수 있는지에 대해 이야기해보겠습니다.

SDK에 OpenAPI Generator 적용하기

Android 프로젝트에 OpenAPI Generator를 적용하는 방법을 살펴볼게요. 해당 작업을 진행하면서 무엇을 했는지, 어떤 기준으로 작업을 진행했는지 공유하려 합니다.

OpenAPI Generator 란?

Open Api Generator 에 대해 들어보신 적 있으신가요? Open API Generator는 OpenAPI Specification(OAS) 문서를 기반으로 클라이언트 SDK, 서버 스텁, 문서를 자동으로 생성해주는 도구입니다. 이를 통해 API 정의서만으로 유지보수 가능한 코드 생성과 통일된 API 요청/응답 처리를 가능하게 합니다.

오늘은 이를 안드로이드 프로젝트에 적용해볼겁니다!

적용 과정

1. Gradle 설정

Open Api Generator를 프로젝트에 추가하려면, 먼저 build.gradle.kts 파일에서 필요한 플러그인을 추가해야 합니다.

plugins {
    id("org.openapi.generator") version "6.6.0"
    id("de.undercouch.download") version "5.6.0"
}

위와 같이 플러그인을 추가한 후 다른 필요한 의존성들도 추가합니다.

dependencies {
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
    implementation("com.squareup.okhttp3:logging-interceptor:4.9.0")
}

2. Swagger 파일 다운로드 설정

Swagger 파일을 원격에서 다운로드해야 하기 때문에 이를 위해 Download 태스크를 사용합니다. 이를 통해 최신 스펙의 Swagger 파일을 얻을 수 있습니다.

아래 코드를 app 모듈 수준 build.gradle 에 추가해줍니다.

tasks.register<Download>("downloadSwagger") {
    src("https://api.example.com/api-json") 
    dest(file("$buildDir/api-swagger.json"))
    onlyIfModified(true)
    useETag(true)
}

3. API 클라이언트 코드 생성하기

이제 Open Api Generator를 사용하여 다운로드한 Swagger 파일을 기반으로 API 클라이언트 코드를 생성하겠습니다.

아래 코드 역시 app 모듈 수준 build.gradle 에 추가해줍니다.

tasks.register<GenerateTask>("generateClient") {
    dependsOn(tasks.named("downloadSwagger"))
    generatorName.set("kotlin")
    inputSpec.set("$buildDir/api-swagger.json")
    outputDir.set("$buildDir/generated")
    apiPackage.set("com.example.api")
    modelPackage.set("com.example.model")
    invokerPackage.set("com.example.invoker")
    configOptions.set(
        mapOf(
            "library" to "jvm-retrofit2",
            "dateLibrary" to "java8",
            "omitGradleWrapper" to "true",
            "sourceFolder" to "src/main/java",
            "useCoroutines" to "false"
        )
    )
}

위 코드는 Open Api Generator를 사용하여 Kotlin 언어로 API 클라이언트를 생성하는 예제입니다. 각 옵션에 대해 자세히 살펴볼까요?

• dependsOn: Swagger를 다운로드를 기다립니다.
• generatorName: 사용할 생성기 이름을 설정합니다. 여기서는 Kotlin을 사용합니다.
• inputSpec: Swagger 파일의 경로를 지정합니다.
• outputDir: 생성된 코드가 출력될 경로를 지정합니다.
• apiPackage, modelPackage, invokerPackage: 각각 API, 모델, 인보커 패키지 위치를 설정합니다.
• configOptions: 기타 설정 옵션들을 지정합니다. 예를 들어, Retrofit2 라이브러리를 사용하고 날짜 라이브러리는 java8을 사용하도록 설정합니다.

4. 코드 생성

위 세팅이 끝났다면, 만들어준 generateClient 명령어를 터미널에 입력하여, 코드를 자동 생성해줍니다.
만약 코드 업데이트를 원하는 경우 아래 명령어를 동일하게 터미널에 입력해주면 됩니다. 😃

./gradlew generateClient

5. 코드 통합

이렇게 생성된 코드를 프로젝트에 통합하여 사용합니다. ApiClient 를 생성하여 사용해주면 됩니다.

// Api 로깅 추가
val apiClient = ApiClient().apply {
    setLogger { message -> println(message) }
}

// 생성된 Api 인터페이스를 객체로 제공
val exampleApi = apiClient.createService(ExampleApi::class.java)

// 자동 생성된 메소드 사용
suspend fun getExampleData() {
    val response = exampleApi.getData() // Api Call
}

위 예제에서는 생성된 ApiClient를 사용하여 API를 호출하는 방법을 보여줍니다.

위 방식을 따르면, 프로젝트에 적용된 2개 이상의 Swagger가 있더라도, 각각의 다른 Swagger 파일을 생성하여, 생성 파일끼리의 충돌로 인한 build error 역시 예방할 수 있습니다.

마치며

Open Api Generator를 사용하면 API 클라이언트 코드를 자동으로 생성할 수 있어, 개발 생산성을 크게 향상시킬 수 있습니다. 이번 기회를 통해 여러분도 프로젝트에 이를 적용해 보세요. 생각보다 간단하고 강력한 도구입니다. 질문이 있으시다면 언제든지 댓글로 남겨주세요. 감사합니다!

🔥 해당 포스팅은 Dev.POST 도움을 받아 작성되었습니다.