Version: 8.x.x

Maven Plugin Client Usage

GraphQL Kotlin plugins can be used to generate a lightweight type-safe GraphQL HTTP clients. See examples below for more information about the client generating tasks.

Downloading Schema SDL

Download SDL Mojo requires target GraphQL server endpoint to be specified. Task can be executed directly from the command line by explicitly specifying graphql.endpoint property.

$ mvn com.expediagroup:graphql-kotlin-maven-plugin:download-sdl -Dgraphql.endpoint="http://localhost:8080/sdl"

Mojo can also be configured in your Maven build file

<plugin>
    <groupId>com.expediagroup</groupId>
    <artifactId>graphql-kotlin-maven-plugin</artifactId>
    <version>${graphql-kotlin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>download-sdl</goal>
            </goals>
            <configuration>
                <endpoint>http://localhost:8080/sdl</endpoint>
            </configuration>
        </execution>
    </executions>
</plugin>

By default, download-sdl goal will be executed as part of the generate-sources build lifecycle phase.

Introspecting Schema

Introspection Mojo requires target GraphQL server endpoint to be specified. Task can be executed directly from the command line by explicitly specifying graphql.endpoint property

$ mvn com.expediagroup:graphql-kotlin-maven-plugin:introspect-schema -Dgraphql.endpoint="http://localhost:8080/graphql"

Mojo can also be configured in your Maven build file

<plugin>
    <groupId>com.expediagroup</groupId>
    <artifactId>graphql-kotlin-maven-plugin</artifactId>
    <version>${graphql-kotlin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>introspect-schema</goal>
            </goals>
            <configuration>
                <endpoint>http://localhost:8080/graphql</endpoint>
            </configuration>
        </execution>
    </executions>
</plugin>

By default, introspect-schema goal will be executed as part of the generate-sources build lifecycle phase.

Generating Client

This Mojo generates GraphQL client code based on the provided queries using target GraphQL schemaFile. Classes are generated under specified packageName. When using default configuration and storing GraphQL queries under src/main/resources directories, task can be executed directly from the command line by explicitly providing required properties.

$ mvn com.expediagroup:graphql-kotlin-maven-plugin:generate-client -Dgraphql.schemaFile="mySchema.graphql" -Dgraphql.packageName="com.example.generated"

Mojo can also be configured in your Maven build file to become part of your build lifecycle. Plugin also provides additional configuration options that are not available on command line.

<plugin>
    <groupId>com.expediagroup</groupId>
    <artifactId>graphql-kotlin-maven-plugin</artifactId>
    <version>${graphql-kotlin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate-client</goal>
            </goals>
            <configuration>
                <packageName>com.example.generated</packageName>
                <schemaFile>mySchema.graphql</schemaFile>
            </configuration>
        </execution>
    </executions>
</plugin>

This will process all GraphQL queries located under src/main/resources and generate corresponding GraphQL Kotlin client data models. Generated classes will be automatically added to the project compile sources.

note

You might need to explicitly add generated clients to your project sources for your IDE to recognize them. See build-helper-maven-plugin for details.

Generating Client with Custom Scalars

By default, all custom GraphQL scalars will be serialized as Strings. You can override this default behavior by specifying custom scalar converter.

For example given following custom scalar in our GraphQL schema

scalar UUID

We can create a custom converter to automatically convert this custom scalar to java.util.UUID

package com.example

import com.expediagroup.graphql.client.converter.ScalarConverter
import java.util.UUID

class UUIDScalarConverter : ScalarConverter<UUID> {
    override fun toScalar(rawValue: Any): UUID = UUID.fromString(rawValue.toString())
    override fun toJson(value: UUID): String = value.toString()
}

Afterwards we need to configure our plugin to use this custom converter

<plugin>
    <groupId>com.expediagroup</groupId>
    <artifactId>graphql-kotlin-maven-plugin</artifactId>
    <version>${graphql-kotlin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate-client</goal>
            </goals>
            <configuration>
                <allowDeprecatedFields>false</allowDeprecatedFields>
                <customScalars>
                    <customScalar>
                        <!-- custom scalar UUID type -->
                        <scalar>UUID</scalar>
                        <!-- fully qualified Java class name of a custom scalar type -->
                        <type>java.util.UUID</type>
                        <!-- fully qualified Java class name of a custom com.expediagroup.graphql.client.converter.ScalarConverter
                           used to convert to/from raw JSON and scalar type -->
                        <converter>com.example.UUIDScalarConverter</converter>
                    </customScalar>
                </customScalars>
                <packageName>com.example.generated</packageName>
                <schemaFile>mySchema.graphql</schemaFile>
            </configuration>
        </execution>
    </executions>
</plugin>

Generating Client using Kotlinx Serialization

GraphQL Kotlin plugins default to generate client data models that are compatible with Jackson. We can change this default behavior by explicitly specifying serializer type and configuring kotlinx.serialization compiler plugin. See kotlinx.serialization documentation for details.

<project>
    <dependencies>
        <!-- other dependencies omitted for clarity -->
        <dependency>
            <groupId>org.jetbrains.kotlinx</groupId>
            <artifactId>kotlinx-serialization-json</artifactId>
            <version>${kotlinx-serialization.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- other plugins omitted for clarity -->
            <plugin>
                <groupId>org.jetbrains.kotlin</groupId>
                <artifactId>kotlin-maven-plugin</artifactId>
                <version>${kotlin.version}</version>
                <configuration>
                    <jvmTarget>1.8</jvmTarget>
                    <compilerPlugins>
                        <plugin>kotlinx-serialization</plugin>
                    </compilerPlugins>
                </configuration>
                <executions>
                    <execution>
                        <id>compile</id>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>test-compile</id>
                        <goals>
                            <goal>test-compile</goal>
                        </goals>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>org.jetbrains.kotlin</groupId>
                        <artifactId>kotlin-maven-serialization</artifactId>
                        <version>${kotlin.version}</version>
                    </dependency>
                </dependencies>
            </plugin>
            <plugin>
                <groupId>com.expediagroup</groupId>
                <artifactId>graphql-kotlin-maven-plugin</artifactId>
                <version>${graphql-kotlin.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate-client</goal>
                        </goals>
                        <configuration>
                            <packageName>com.example.generated</packageName>
                            <schemaFile>mySchema.graphql</schemaFile>
                            <!-- optional configuration below -->
                            <serializer>KOTLINX</serializer>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Generating Test Client

This Mojo generates GraphQL Kotlin test client code based on the provided queries using target GraphQL schemaFile. Classes are generated under specified packageName. When using default configuration and storing GraphQL queries under src/test/resources directories, task can be executed directly from the command line by explicitly providing required properties.

$ mvn com.expediagroup:graphql-kotlin-maven-plugin:generate-test-client -Dgraphql.schemaFile="mySchema.graphql" -Dgraphql.packageName="com.example.generated"

Mojo can also be configured in your Maven build file to become part of your build lifecycle. Plugin also provides additional configuration options that are not available on command line.

<plugin>
    <groupId>com.expediagroup</groupId>
    <artifactId>graphql-kotlin-maven-plugin</artifactId>
    <version>${graphql-kotlin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate-test-client</goal>
            </goals>
            <configuration>
                <packageName>com.example.generated</packageName>
                <schemaFile>mySchema.graphql</schemaFile>
            </configuration>
        </execution>
    </executions>
</plugin>

This will process all GraphQL queries located under src/test/resources and generate corresponding GraphQL Kotlin test clients. Generated classes will be automatically added to the project test compile sources.

note

You might need to explicitly add generated test clients to your project test sources for your IDE to recognize them. See build-helper-maven-plugin for details.

Minimal Configuration Example

Following is the minimal configuration that runs introspection query against a target GraphQL server and generates a corresponding schema. This generated schema is subsequently used to generate GraphQL client code based on the queries provided under src/main/resources directory.

<plugin>
    <groupId>com.expediagroup</groupId>
    <artifactId>graphql-kotlin-maven-plugin</artifactId>
    <version>${graphql-kotlin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>introspect-schema</goal>
                <goal>generate-client</goal>
            </goals>
            <configuration>
                <endpoint>http://localhost:8080/graphql</endpoint>
                <packageName>com.example.generated</packageName>
            </configuration>
        </execution>
    </executions>
</plugin>

info

Both introspect-schema and generate-client goals are bound to the same generate-sources Maven lifecycle phase. As opposed to Gradle, Maven does not support explicit ordering of different goals bound to the same build phase. Maven Mojos will be executed in the order they are defined in your pom.xml build file.

Complete Configuration Example

Following is a configuration example that downloads schema SDL from a target GraphQL server that is then used to generate the GraphQL client data models using kotlinx.serialization that are based on the provided query.

<project>
    <dependencies>
        <!-- other dependencies omitted for clarity -->
        <dependency>
            <groupId>org.jetbrains.kotlinx</groupId>
            <artifactId>kotlinx-serialization-json</artifactId>
            <version>${kotlinx-serialization.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- other plugins omitted for clarity -->
            <plugin>
                <groupId>org.jetbrains.kotlin</groupId>
                <artifactId>kotlin-maven-plugin</artifactId>
                <version>${kotlin.version}</version>
                <configuration>
                    <jvmTarget>1.8</jvmTarget>
                    <compilerPlugins>
                        <plugin>kotlinx-serialization</plugin>
                    </compilerPlugins>
                </configuration>
                <executions>
                    <execution>
                        <id>compile</id>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>test-compile</id>
                        <goals>
                            <goal>test-compile</goal>
                        </goals>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>org.jetbrains.kotlin</groupId>
                        <artifactId>kotlin-maven-serialization</artifactId>
                        <version>${kotlin.version}</version>
                    </dependency>
                </dependencies>
            </plugin>
            <plugin>
                <groupId>com.expediagroup</groupId>
                <artifactId>graphql-kotlin-maven-plugin</artifactId>
                <version>${graphql-kotlin.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>download-sdl</goal>
                            <goal>generate-client</goal>
                        </goals>
                        <configuration>
                            <endpoint>http://localhost:8080/sdl</endpoint>
                            <packageName>com.example.generated</packageName>
                            <!-- optional configuration below -->
                            <schemaFile>${project.build.directory}/mySchema.graphql</schemaFile>
                            <allowDeprecatedFields>true</allowDeprecatedFields>
                            <customScalars>
                                <customScalar>
                                    <!-- custom scalar UUID type -->
                                    <scalar>UUID</scalar>
                                    <!-- fully qualified Java class name of a custom scalar type -->
                                    <type>java.util.UUID</type>
                                    <!-- fully qualified Java class name of a custom com.expediagroup.graphql.client.converter.ScalarConverter
                                       used to convert to/from raw JSON and scalar type -->
                                    <converter>com.example.UUIDScalarConverter</converter>
                                </customScalar>
                            </customScalars>
                            <headers>
                                <X-Custom-Header>My-Custom-Header</X-Custom-Header>
                            </headers>
                            <timeoutConfiguration>
                                <!-- timeout values in milliseconds -->
                                <connect>1000</connect>
                                <read>30000</read>
                            </timeoutConfiguration>
                            <queryFiles>
                                <queryFile>${project.basedir}/src/main/resources/queries/MyQuery.graphql</queryFile>
                            </queryFiles>
                            <serializer>KOTLINX</serializer>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Generating Multiple Clients

In order to generate GraphQL clients targeting multiple endpoints, we need to configure separate executions targeting different endpoints.

<plugin>
    <groupId>com.expediagroup</groupId>
    <artifactId>graphql-kotlin-maven-plugin</artifactId>
    <version>${graphql-kotlin.version}</version>
    <executions>
        <execution>
            <id>generate-first-client</id>
            <goals>
                <goal>introspect-schema</goal>
                <goal>generate-client</goal>
            </goals>
            <configuration>
                <endpoint>http://localhost:8080/graphql</endpoint>
                <packageName>com.example.generated.first</packageName>
                <queryFiles>
                    <queryFile>${project.basedir}/src/main/resources/queries/FirstQuery.graphql</queryFile>
                </queryFiles>
            </configuration>
        </execution>
        <execution>
            <id>generate-second-client</id>
            <goals>
                <goal>introspect-schema</goal>
                <goal>generate-client</goal>
            </goals>
            <configuration>
                <endpoint>http://localhost:8081/graphql</endpoint>
                <packageName>com.example.generated.second</packageName>
                <queryFiles>
                    <queryFile>${project.basedir}/src/main/resources/queries/SecondQuery.graphql</queryFile>
                </queryFiles>
            </configuration>
        </execution>
    </executions>
</plugin>

Downloading Schema SDL​

Introspecting Schema​

Generating Client​

Generating Client with Custom Scalars​

Generating Client using Kotlinx Serialization​

Generating Test Client​

Minimal Configuration Example​

Complete Configuration Example​

Generating Multiple Clients​