Skip to content

[java/kotlin client] update graphql-kotlin client documentation #1077

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 19, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,20 @@ url: https://github.com/ExpediaGroup/graphql-kotlin/
github: ExpediaGroup/graphql-kotlin
---

GraphQL Kotlin provides a set of lightweight type-safe GraphQL HTTP clients. The library provides Ktor HTTP client and Spring WebClient based reference implementations as well as allows for custom implementations using other engines. Type-safe data models are generated at build time by the GraphQL Kotlin Gradle and Maven plugins.
GraphQL Kotlin provides a set of lightweight type-safe GraphQL HTTP clients. The library provides Ktor HTTP client and Spring WebClient based reference implementations as well as allows for custom implementations using other engines. Jackson and kotlinx-serialization type-safe data models are generated at build time by the provided Gradle and Maven plugins.

To generate Ktor based GraphQL client add following to your Gradle build file:
To generate Jackson models that will be used with GraphQL Kotlin Spring WebClient, add following to your Gradle build file:

```kotlin
// build.gradle.kts
import com.expediagroup.graphql.plugin.generator.GraphQLClientType
import com.expediagroup.graphql.plugin.gradle.graphql

plugins {
id("com.expediagroup.graphql") version $latestGraphQLKotlinVersion
}

dependencies {
implementation("com.expediagroup:graphql-kotlin-ktor-client:$latestGraphQLKotlinVersion")
implementation("com.expediagroup:graphql-kotlin-spring-client:$latestGraphQLKotlinVersion")
}

graphql {
Expand All @@ -28,61 +27,59 @@ graphql {
endpoint = "http://localhost:8080/graphql"
// package for generated client code
packageName = "com.example.generated"
clientType = GraphQLClientType.KTOR
}
}
```

By default, GraphQL Kotlin plugin will look for query files under `src/main/resources`. Given `helloWorld: String!` query we can add following `HelloWorldQuery.graphql` sample query to our repo:
By default, GraphQL Kotlin plugins will look for query files under `src/main/resources`. Given `HelloWorldQuery.graphql` sample query:

```graphql
query HelloWorldQuery {
helloWorld
}
```

Plugin will generate following client code:
Plugin will generate classes that are simple POJOs implementing GraphQLClientRequest interface and represent a GraphQL request.

```kotlin
package com.example.generated

import com.expediagroup.graphql.client.GraphQLKtorClient
import com.expediagroup.graphql.types.GraphQLResponse
import com.expediagroup.graphql.client.types.GraphQLClientRequest
import kotlin.String
import kotlin.reflect.KClass

const val HELLO_WORLD_QUERY: String = "query HelloWorldQuery {\n helloWorld\n}"

class HelloWorldQuery(
private val graphQLClient: GraphQLKtorClient<*>
) {
suspend fun execute(requestBuilder: HttpRequestBuilder.() -> Unit = {}): GraphQLResponse<HelloWorldQuery.Result> =
graphQLClient.execute(HELLO_WORLD_QUERY, "HelloWorldQuery", null, requestBuilder)
class HelloWorldQuery: GraphQLClientRequest<HelloWorldQuery.Result> {
override val query: String = HELLO_WORLD_QUERY

data class Result(
val helloWorld: String
)
override val operationName: String = "HelloWorldQuery"

override fun responseType(): KClass<HelloWorldQuery.Result> = HelloWorldQuery.Result::class

data class Result(
val helloWorld: String
}
}
```

We can then execute the client
We can then execute our queries using target client.

```kotlin
package com.example.client

import com.expediagroup.graphql.client.GraphQLKtorClient
import com.expediagroup.graphql.client.spring.GraphQLWebClient
import com.expediagroup.graphql.generated.HelloWorldQuery
import kotlinx.coroutines.runBlocking
import java.net.URL

fun main() {
val client = GraphQLKtorClient(url = URL("http://localhost:8080/graphql"))
val helloWorldQuery = HelloWorldQuery(client)
val client = GraphQLWebClient(url = "http://localhost:8080/graphql")
runBlocking {
val result = helloWorldQuery.execute()
val helloWorldQuery = HelloWorldQuery()
val result = client.execute(helloWorldQuery)
println("hello world query result: ${result.data?.helloWorld}")
}
client.close()
}
```

See [graphql-kotlin docs](https://expediagroup.github.io/graphql-kotlin/docs/getting-started) for additional details.
See [graphql-kotlin client docs](https://opensource.expediagroup.com/graphql-kotlin/docs/client/client-overview) for additional details.