Skip to main content
Version: 7.x.x

Maven Plugin Goals

GraphQL Kotlin Maven Plugin provides functionality to generate a lightweight GraphQL HTTP client and generate GraphQL schema directly from your source code.

info

This plugin is dependent on Kotlin compiler plugin as it generates Kotlin source code that needs to be compiled.

Goals

You can find detailed information about graphql-kotlin-maven-plugin and all its goals by running mvn help:describe -Dplugin=com.expediagroup:graphql-kotlin-maven-plugin -Ddetail.

download-sdl

GraphQL endpoints are often public and as such many servers might disable introspection queries in production environment. Since GraphQL schema is needed to generate type safe clients, as alternative GraphQL servers might expose private endpoints (e.g. accessible only from within network, etc) that could be used to download schema in Schema Definition Language (SDL) directly. This Mojo attempts to download schema from the specified graphql.endpoint, validates the result whether it is a valid schema and saves it locally in a specified target file (defaults to schema.graphql under build directory). In general, this goal provides limited functionality by itself and instead should be used to generate input for the subsequent generate-client goal.

Attributes

  • Default Lifecycle Phase: generate-sources

Parameters

PropertyTypeRequiredDescription
endpointStringyesTarget GraphQL server SDL endpoint that will be used to download schema.
User property is: graphql.endpoint.
headersMap<String, Any>Optional HTTP headers to be specified on a SDL request.
timeoutConfigurationTimeoutConfigurationOptional timeout configuration (in milliseconds) to download schema from SDL endpoint before we cancel the request.
Default values are:
connect timeout = 5000
read timeout = 15000.
schemaFileFileTarget schema file.
Default value is: ${project.build.directory}/schema.graphql
User property is: graphql.schemaFile.

Parameter Details

  • timeoutConfiguration - Timeout configuration that allows you to specify connect and read timeout values in milliseconds.
<timeoutConfiguration>
<!-- timeout values in milliseconds -->
<connect>1000</connect>
<read>30000</read>
</timeoutConfiguration>

generate-client

Generate GraphQL client code based on the provided GraphQL schema and target queries.

Attributes

  • Default Lifecycle Phase: generate-sources
  • Requires Maven Project
  • Generated classes are automatically added to the list of compiled sources.

Parameters

PropertyTypeRequiredDescription
allowDeprecatedFieldsBooleanBoolean flag indicating whether selection of deprecated fields is allowed or not.
Default value is: false.
User property is: graphql.allowDeprecatedFields.
customScalarsList<CustomScalar>List of custom GraphQL scalar to converter mappings containing information about corresponding Java type and converter that should be used to serialize/deserialize values.
outputDirectoryFileTarget directory where to store generated files.
Default value is: ${project.build.directory}/generated-sources/graphql
packageNameStringyesTarget package name for generated code.
User property is: graphql.packageName.
parserOptionsGraphQLParserOptionsConfigures the settings used when parsing GraphQL queries and schema definition language documents.
queryFileDirectoryFileDirectory file containing GraphQL queries. Instead of specifying a directory you can also specify list of query file by using queryFiles property instead.
Default value is: src/main/resources.
queryFilesList<File>List of query files to be processed. Instead of a list of files to be processed you can also specify queryFileDirectory directory containing all the files. If this property is specified it will take precedence over the corresponding directory property.
schemaFileStringGraphQL schema file that will be used to generate client code.
Default value is: ${project.build.directory}/schema.graphql
User property is: graphql.schemaFile.
serializerGraphQLSerializerJSON serializer that will be used to generate the data classes.
Default value is: GraphQLSerializer.JACKSON.
useOptionalInputWrapperBooleanBoolean opt-in flag to wrap nullable arguments in OptionalInput that distinguish between null and undefined/omitted value.
Default value is: false.
User property is: graphql.useOptionalInputWrapper

Parameter Details

  • customScalars - List of custom GraphQL scalars. Objects contain target GraphQL scalar name, corresponding Java type and converter that should be used to serialize/deserialize values.
<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>
  • parserOptions - Configure options for parsing GraphQL queries and schema definition language documents. Settings here override the defaults set by GraphQL Java.
  <parserOptions>
<!-- Modify the maximum number of tokens read to prevent processing extremely large queries -->
<maxTokens>15000</maxTokens>
<!-- Modify the maximum number of whitespace tokens read to prevent processing extremely large queries -->
<maxWhitespaceTokens>200000</maxWhitespaceTokens>
<!-- Modify the maximum number of characters in a document to prevent malicious documents consuming CPU -->
<maxCharacters>1048576</maxCharacters>
<!-- Modify the maximum grammar rule depth to negate malicious documents that can cause stack overflows -->
<maxRuleDepth>500</maxRuleDepth>
<!-- Memory usage is significantly reduced by not capturing ignored characters, especially in SDL parsing -->
<captureIgnoredChars>false</captureIgnoredChars>
<!-- Single-line comments do not have any semantic meaning in GraphQL source documents and can be ignored -->
<captureLineComments>true</captureLineComments>
<!-- Memory usage is reduced by not setting SourceLocations on AST nodes, especially in SDL parsing. -->
<captureSourceLocation>true</captureSourceLocation>
</parserOptions>

generate-graalvm-metadata

Generates GraalVM Reachability Metadata for graphql-kotlin servers. Based on the GraphQL schema it will generate native-image.properties, reflect-config.json and resource-config.json metadata files under target/classes/META-INF/native-image/<groupId>/<projectName>/graphql

This task should be used in tandem with GraalVM Native Plugin to simplify generation of GraalVM native graphql-kotlin servers.

Attributes

  • Default Lifecycle Phase: process-classes
  • Requires Maven Project

Parameters

PropertyTypeRequiredDescription
packagesList<String>yesList of supported packages that can be can contain GraphQL schema.
mainClassNameStringApplication main class name.

generate-sdl

Generates GraphQL schema in SDL format from your source code using reflections. Utilizes graphql-kotlin-schema-generator to generate the schema from classes implementing graphql-kotlin-server marker Query, Mutation and Subscription interfaces. In order to limit the amount of packages to scan, this mojo requires users to provide a list of packages that can contain GraphQL types.

This MOJO utilizes ServiceLoader mechanism to dynamically load available SchemaGeneratorHooksProvider service providers from the classpath. Service provider can be provided as part of your project, included in one of your project dependencies or through explicitly provided artifact. See Schema Generator Hooks Provider for additional details on how to create custom hooks service provider. Configuration below shows how to configure GraphQL Kotlin plugin with explicitly provided artifact.

Attributes

  • Default Lifecycle Phase: process-classes
  • Requires Maven Project

Parameters

PropertyTypeRequiredDescription
packagesList<String>yesList of supported packages that can be scanned to generate SDL.
schemaFileFileTarget GraphQL schema file to be generated.
Default value is: ${project.buildDir}/schema.graphql

generate-test-client

Generate GraphQL test client code based on the provided GraphQL schema and target queries.

Attributes

  • Default Lifecycle Phase: generate-test-sources
  • Requires Maven Project
  • Generated classes are automatically added to the list of test compiled sources.

Parameters

PropertyTypeRequiredDescription
allowDeprecatedFieldsBooleanBoolean flag indicating whether selection of deprecated fields is allowed or not.
Default value is: false.
User property is: graphql.allowDeprecatedFields.
customScalarsList<CustomScalar>List of custom GraphQL scalar to converter mappings containing information about corresponding Java type and converter that should be used to serialize/deserialize values.
outputDirectoryFileTarget directory where to store generated files.
Default value is: ${project.build.directory}/generated-test-sources/graphql
packageNameStringyesTarget package name for generated code.
User property is: graphql.packageName.
queryFileDirectoryFileDirectory file containing GraphQL queries. Instead of specifying a directory you can also specify list of query file by using queryFiles property instead.
Default value is: src/test/resources.
queryFilesList<File>List of query files to be processed. Instead of a list of files to be processed you can also specify queryFileDirectory directory containing all the files. If this property is specified it will take precedence over the corresponding directory property.
serializerGraphQLSerializerJSON serializer that will be used to generate the data classes.
Default value is: GraphQLSerializer.JACKSON.
schemaFileStringGraphQL schema file that will be used to generate client code.
Default value is: ${project.build.directory}/schema.graphql
User property is: graphql.schemaFile.
useOptionalInputWrapperBooleanBoolean opt-in flag to wrap nullable arguments in OptionalInput that distinguish between null and undefined/omitted value.
Default value is: false.
User property is: graphql.useOptionalInputWrapper

Parameter Details

  • customScalars - List of custom GraphQL scalars. Objects contain target GraphQL scalar name, corresponding Java type and converter that should be used to serialize/deserialize values.

<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>

  • parserOptions - Configure options for parsing GraphQL queries and schema definition language documents. Settings here override the defaults set by GraphQL Java.

      <parserOptions>
    <!-- Modify the maximum number of tokens read to prevent processing extremely large queries -->
    <maxTokens>15000</maxTokens>
    <!-- Modify the maximum number of whitespace tokens read to prevent processing extremely large queries -->
    <maxWhitespaceTokens>200000</maxWhitespaceTokens>
    <!-- Modify the maximum number of characters in a document to prevent malicious documents consuming CPU -->
    <maxCharacters>1048576</maxCharacters>
    <!-- Modify the maximum grammar rule depth to negate malicious documents that can cause stack overflows -->
    <maxRuleDepth>500</maxRuleDepth>
    <!-- Memory usage is significantly reduced by not capturing ignored characters, especially in SDL parsing -->
    <captureIgnoredChars>false</captureIgnoredChars>
    <!-- Single-line comments do not have any semantic meaning in GraphQL source documents and can be ignored -->
    <captureLineComments>true</captureLineComments>
    <!-- Memory usage is reduced by not setting SourceLocations on AST nodes, especially in SDL parsing. -->
    <captureSourceLocation>true</captureSourceLocation>
    </parserOptions>

introspect-schema

Executes GraphQL introspection query against specified graphql.endpoint and saves the result locally to a target file (defaults to schema.graphql under build directory). In general, this goal provides limited functionality by itself and instead should be used to generate input for the subsequent generate-client goal.

Attributes

  • Default Lifecycle Phase: generate-sources

Parameters

PropertyTypeRequiredDescription
endpointStringyesTarget GraphQL server endpoint that will be used to execute introspection queries.
User property is: graphql.endpoint.
headersMap<String, Any>Optional HTTP headers to be specified on an introspection query.
timeoutConfigurationTimeoutConfigurationOptional timeout configuration (in milliseconds) to download schema from SDL endpoint before we cancel the request.
Default values are:
connect timeout = 5000
read timeout = 15000.
schemaFileFileTarget schema file.
Default value is: ${project.build.directory}/schema.graphql
User property is: graphql.schemaFile.
streamResponseBooleanBoolean property to indicate whether to use streamed (chunked) responses.
Default value is**: true.

Parameter Details

  • timeoutConfiguration - Timeout configuration that allows you to specify connect and read timeout values in milliseconds.
<timeoutConfiguration>
<!-- timeout values in milliseconds -->
<connect>1000</connect>
<read>30000</read>
</timeoutConfiguration>