Generates GraphQL document wrappers and type-safe query classes integrated into build tasks. Supports custom type mapping and can be used with HTTP clients for seamless GraphQL API interaction.
GraphQL Document wrapper generator for Kotlin Multiplatform Project.
Currently, available for JVM/Android/iOS
kgql core classes
kgql Gradle Plugin generates wrapper classes for provided GraphQL document files.
kgql requires Gradle 7.0 or later
Supported GraphQL file extension: .gql or .graphql
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"
]
}
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"
]
}
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.
ktor extensions for kgql
# viewer.gql
query {
viewer {
login
}
}
Below code will be generated from above GraphQL document file(viewer.gql).
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
Have a look at ./sample directory.
# Try out the samples.
# BuildKonfig will be generated in ./sample/build/kgql
$ ./gradlew -p sample generateKgqlInterface
# Try out the samples.
# BuildKonfig will be generated in ./sample/build/kgql
$ ./gradlew clean build installArchives
$ ./gradlew -p sample generateKgqlInterface
This library is highly inspired by squareup/sqldelight and the gradle plugin and basic idea is heavily based on it. Thanks for this.
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()
data class Request(
override val variables: Unit? = null,
override val operationName: String? =
null,
override val query: String = document
) : KgqlRequestBody<Unit>
}
}
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"
data class ViewerWrapper(
val viewer: Viewer
)
data class Viewer(
val login: String
)
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
}
}
Surfaced from shared tags and platforms — no rankings paid for.