kgql

GraphQL Document wrapper generator for Kotlin Multiplatform Project.
Currently, available for JVM/Android/iOS

core

kgql core classes

kgql-gradle-plugin

kgql Gradle Plugin generates wrapper classes for provided GraphQL document files.

Setup

kgql requires Gradle 7.0 or later

Supported GraphQL file extension: .gql or .graphql

For Android Project

buildscript {
    repositories {
        mavenCentral()
        google()
        jcenter()
    }
    dependencies {
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10'
        classpath 'org.jetbrains.kotlin:kotlin-serialization:1.3.2'
        classpath 'com.codingfeline.kgql:gradle-plugin:0.9.0'
    }
}

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'kotlinx-serialization'
apply plugin: 'com.codingfeline.kgql'

repositories {
     mavenCentral()
}

kgql {
    packageName = "com.sample"
    sourceSet = files("src/main/kgql")
    typeMapper = [
        // mapper for non-scalar type
        "UserProfile": "com.sample.data.UserProfile"
    ]
}

For Kotlin Multiplatform Project

buildscript {
    repositories {
        mavenCentral()
        google()
        jcenter()
    }
    dependencies {
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10'
        classpath 'org.jetbrains.kotlin:kotlin-serialization:1.3.2'
        classpath 'com.codingfeline.kgql:gradle-plugin:0.9.0'
    }
}

apply plugin: 'kotlin-multiplatform'
apply plugin: 'kotlinx-serialization'
apply plugin: 'com.codingfeline.kgql'

repositories {
     mavenCentral()
}

kotlin {
    // kotlin configurations...
}

kgql {
    packageName = "com.sample"
    sourceSet = files("src/main/kgql")
    typeMapper = [
        // mapper for non-scalar type
        "UserProfile": "com.sample.data.UserProfile"
    ]
}

How to generate wrapper classes

When you apply kgql plugin, generateKgqlInterface task is added to the project. Manually executing it is one way, but the task is integrated into project's build task, so it will be generated upon each build.

[WIP]kgql-ktor

ktor extensions for kgql

How it works

# viewer.gql
query {
  viewer {
    login
  }
}

Below code will be generated from above GraphQL document file(viewer.gql).

package com.sample

import com.codingfeline.kgql.core.KgqlRequestBody
import kotlin.String
import kotlin.Unit
import kotlinx.serialization.KSerializer
import kotlinx.serialization.Optional
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

object ViewerDocument {
    private val document: String = """
            |query {
            |  viewer {
            |    login
            |  }
            |}
            |""".trimMargin()

    object Query {
        /**
         * Create an instance of [Request] which then you can encode to JSON string
         */
        fun requestBody(): Request = Request()

        fun serializer(): KSerializer<Request> = Request.serializer()

        @Serializable
        data class Request(
            @SerialName(value = "variables") @Optional override val variables: Unit? = null,
            @Optional @SerialName(value = "operationName") override val operationName: String? =
                null,
            @SerialName(value = "query") override val query: String = document
        ) : KgqlRequestBody<Unit>
    }
}

As you can see, generated code utilizes data class's default value. So in order to properly serialize, you need to set encodeDefaults to true in your kotlinx.serialization.json.Json instance.

You can use this code with Ktor or any other HttpClient.

Example usage with Ktor is below

package com.sample

import com.codingfeline.kgql.core.KgqlResponse
import com.codingfeline.kgql.core.KgqlError
import com.sample.ViewerDocument
import io.ktor.client.HttpClient
import io.ktor.client.features.json.JsonFeature
import io.ktor.client.request.headers
import io.ktor.client.request.post
import io.ktor.http.ContentType
import io.ktor.http.content.TextContent
import io.ktor.http.Url
import kotlinx.serialization.json.JSON
import kotlinx.serialization.Serializable

const val TOKEN = "YOUR_GITHUB_TOKEN"

@Serializable
data class ViewerWrapper(
    val viewer: Viewer
)

@Serializable
data class Viewer(
    val login: String
)

@Serializable
data class ViewerResponse(
    override val data: ViewerWrapper?,
    override val errors: List<KgqlError>?
) : KgqlResponse<ViewerWrapper>

class GitHubApi {

    private val json = Json {
        // encodeDefaults must be set to true
        encodeDefaults = true
    }

    private val client = HttpClient {
        install(JsonFeature) {
            this.serializer = KotlinxSerializer(json = json)
        }
    }

    suspend fun fetchLogin(): Viewer? {

        val body = json.encodeToString(ViewerDocument.Query.serializer(), ViewerDocument.Query.requestBody())
        val response = client.post<String>(url = Url("https://api.github.com/graphql")) {
            body = TextContent(text = body, contentType = ContentType.Application.Json)

            headers {
                append("Authorization", "bearer $TOKEN")
            }
        }

        val res = JSON.parse(ViewerResponse.serializer(), response)

        return res.data?.viewer
    }
}

Try out the sample

Have a look at ./sample directory.

# Try out the samples.
# BuildKonfig will be generated in ./sample/build/kgql
$ ./gradlew -p sample generateKgqlInterface

Try sample with snapshot

# Try out the samples.
# BuildKonfig will be generated in ./sample/build/kgql
$ ./gradlew clean build installArchives
$ ./gradlew -p sample generateKgqlInterface

Credits

This library is highly inspired by squareup/sqldelight and the gradle plugin and basic idea is heavily based on it. Thanks for this.