gradle

GraphQL Codegen Gradle plugin

• Description
• Plugin Setup
• Plugin Options
• Sample Plugin Configuration
  • External mapping configuration
• Examples
  • GraphQL server code generation
  • GraphQL client code generation
• Different configurations for graphql schemas
• Convert generated Java classes to Kotlin classes

Description

This Gradle plugin is able to generate the following classes based on your GraphQL schema:

• Interfaces for GraphQL queries, mutations and subscriptions
• Interfaces for GraphQL unions
• POJO classes for GraphQL types/inputs
• Enum classes for GraphQL enums
• Interface Resolvers for GraphQL type fields
• Client Request classes for GraphQL queries, mutations and subscriptions

Plugin Setup

plugins {
  id "io.github.kobylynskyi.graphql.codegen" version "1.7.4"
}

Using legacy plugin application:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "io.github.kobylynskyi.graphql.codegen:graphql-codegen-gradle-plugin:1.7.4"
  }
}

apply plugin: "io.github.kobylynskyi.graphql.codegen"

Plugin Options

Option	Data Type	Default value	Description
graphqlSchemaPaths	List(String)	(falls back to graphqlSchemas)	GraphQL schema locations. You can supply multiple paths to GraphQL schemas. To include many schemas from a folder hierarchy, use the graphqlSchemas block instead.
graphqlSchemas	See graphqlSchemas	All .graphqls/.graphql files in resources	Block to define the input GraphQL schemas, when exact paths are too cumbersome. See table below for a list of options.
outputDir	String	None	The output target directory into which code will be generated.
jsonConfigurationFile	String	Empty	Path to an external mapping configuration.
packageName	String	Empty	Java package for generated classes.
apiPackageName	String	Empty	Java package for generated api classes (Query, Mutation, Subscription).
modelPackageName	String	Empty	Java package for generated model classes (type, input, interface, enum, union).
generateBuilder	Boolean	True	Specifies whether generated model classes should have builder.
generateApis	Boolean	True	Specifies whether api classes should be generated as well as model classes.
generateAsyncApi	Boolean	False	If true, then wrap type into java.util.concurrent.CompletableFuture or subscriptionReturnType
generateDataFetchingEnvironmentArgumentInApis	Boolean	False	If true, then graphql.schema.DataFetchingEnvironment env will be added as a last argument to all methods of root type resolvers and field resolvers.
generateEqualsAndHashCode	Boolean	False	Specifies whether generated model classes should have equals and hashCode methods defined.
generateToString	Boolean	False	Specifies whether generated model classes should have toString method defined.
modelNamePrefix	String	Empty	Sets the prefix for GraphQL model classes (type, input, interface, enum, union).
modelNameSuffix	String	Empty	Sets the suffix for GraphQL model classes (type, input, interface, enum, union).
modelValidationAnnotation	String	@javax.validation. constraints.NotNull	Annotation for mandatory (NonNull) fields. Can be null/empty.
customTypesMapping	Map(String,String)	Empty	Can be used to supply custom mappings for scalars. Supports: * Map of (GraphqlObjectName.fieldName) to (JavaType) * Map of (GraphqlType) to (JavaType)
customAnnotationsMapping	Map(String,String)	Empty	Can be used to supply custom annotations (serializers) for scalars. Supports: * Map of (GraphqlObjectName.fieldName) to (JavaAnnotation) * Map of (GraphqlType) to (JavaAnnotation)
fieldsWithResolvers	Set(String)	Empty	Fields that require Resolvers should be defined here in format: TypeName.fieldName or TypeName.
fieldsWithoutResolvers	Set(String)	Empty	Fields that DO NOT require Resolvers should be defined here in format: TypeName.fieldName or TypeName. Can be used in conjunction with generateExtensionFieldsResolvers option.
generateParameterizedFieldsResolvers	Boolean	True	If true, then generate separate Resolver interface for parametrized fields. If false, then add field to the type definition and ignore field parameters.
generateExtensionFieldsResolvers	Boolean	False	Specifies whether all fields in extensions (extend type and extend interface) should be present in Resolver interface instead of the type class itself.
subscriptionReturnType	String	Empty	Return type for subscription methods. For example: org.reactivestreams.Publisher, io.reactivex.Observable, etc.
generateRequests	Boolean	False	Specifies whether client-side classes should be generated for each query, mutation and subscription. This includes: Request class (contains input data) and ResponseProjection class (contains response fields).
requestSuffix	String	Request	Sets the suffix for Request classes.
responseProjectionSuffix	String	ResponseProjection	Sets the suffix for ResponseProjection classes.
parametrizedInputSuffix	String	ParametrizedInput	Sets the suffix for ParametrizedInput classes.
parentInterfaces	See parentInterfaces	Empty	Block to define parent interfaces for generated interfaces (query / mutation / subscription / type resolver)

Option graphqlSchemas

When exact paths to GraphQL schemas are too cumbersome to provide in the graphqlSchemaPaths, use the <graphqlSchemas></graphqlSchemas> block. The parameters inside that block are the following:

Key inside graphqlSchemas	Data Type	Default value	Description
rootDir	String	Main resources dir	The root directory from which to start searching for schema files.
recursive	Boolean	true	Whether to recursively look into sub directories.
includePattern	String	.*\.graphqls?	A Java regex that file names must match to be included. It should be a regex as defined by the Pattern JDK class. It will be used to match only the file name without path.
excludedFiles	Set	(empty set)	A set of files to exclude, even if they match the include pattern. These paths should be either absolute or relative to the provided rootDir.

Option parentInterfaces

Following options can be defined if you want generated resolvers to extend certain interfaces. Can be handy if you are using graphql-java-tools and want your resolver classes to extend only interfaces generated by this plugin.

Note: if you want to include a GraphQL type name into the interface name, then use {{TYPE}} placeholder. E.g.: graphql.kickstart.tools.GraphQLResolver<{{TYPE}}>

Key inside parentInterfaces	Data Type	Default value	Description
queryResolver	String	Empty	Interface that will be added as "extend" to all generated api Query interfaces.
mutationResolver	String	Empty	Interface that will be added as "extend" to all generated api Mutation interfaces.
subscriptionResolver	String	Empty	Interface that will be added as "extend" to all generated api Subscription interfaces.
resolver	String	Empty	Interface that will be added as "extend" to all generated TypeResolver interfaces.

Sample Plugin Configuration

build.gradle:

graphqlCodegen {
    graphqlSchemaPaths = [
        "$projectDir/src/main/resources/schema.graphqls".toString()
    ]
    outputDir = new File("$buildDir/generated")
    packageName = "com.example.graphql.model"
    customTypesMapping = [
        DateTime: "org.joda.time.DateTime",
        Price.amount: "java.math.BigDecimal"
    ]
    customAnnotationsMapping = [
        DateTime: "com.fasterxml.jackson.databind.annotation.JsonDeserialize(using = com.example.json.EpochMillisScalarDeserializer.class"
    ]
    modelNameSuffix = "TO"
}

// Automatically generate GraphQL code on project build:
compileJava.dependsOn 'graphqlCodegen'

// Add generated sources to your project source sets:
sourceSets.main.java.srcDir "$buildDir/generated"

You can also refer to build.gradle files in example projects: example-client/build.gradle, example-server/build.gradle

build.gradle.kts:

tasks.named<GraphqlCodegenGradleTask>("graphqlCodegen") {
    graphqlSchemaPaths = listOf("$projectDir/src/main/resources/graphql/schema.graphqls".toString())
    outputDir = new File("$buildDir/generated")
    packageName = "com.example.graphql.model"
    customTypesMapping = mutableMapOf(Pair("EpochMillis", "java.time.LocalDateTime"))
    customAnnotationsMapping = mutableMapOf(Pair("EpochMillis", "com.fasterxml.jackson.databind.annotation.JsonDeserialize(using = com.example.json.EpochMillisScalarDeserializer.class"))
}

// Automatically generate GraphQL code on project build:
sourceSets {
    getByName("main").java.srcDirs("$buildDir/generated")
}

// Add generated sources to your project source sets:
val check: DefaultTask by tasks
val graphqlCodegen: DefaultTask by tasks
check.dependsOn(graphqlCodegen)    

External mapping configuration

Provide a path to external file via property jsonConfigurationFile Sample content of the file:

{
  "generateApis": true,
  "packageName": "com.kobylynskyi.graphql.testconfigjson",
  "customTypesMapping": {
    "Price.amount": "java.math.BigDecimal"
  }
}

Examples

GraphQL server code generation

example-server:

• Plugin configuration in build.gradle
• GraphQL Resolver classes that implement generated interfaces

GraphQL client code generation

example-client:

• Plugin configuration in build.gradle
• Building GraphQL request and parsing response using Spring RestTemplate
• Building GraphQL request and parsing response using RestAssured

Different configurations for graphql schemas

If you want to have different configuration for different .graphqls files (e.g.: different javaPackage, outputDir, etc.), then you will need to create separate gradle tasks for each set of schemas. E.g.:

task graphqlCodegenService1(type: GraphqlCodegenGradleTask) {
    graphqlSchemaPaths = ["$projectDir/src/main/resources/schema1.graphqls".toString()]
    outputDir = new File("$buildDir/generated/example1")
}

task graphqlCodegenService2(type: GraphqlCodegenGradleTask) {
    graphqlSchemaPaths = ["$projectDir/src/main/resources/schema2.graphqls".toString()]
    outputDir = new File("$buildDir/generated/example2")
}

Later on you can call each task separately or together:

• gradle clean graphqlCodegenService1 build
• gradle clean graphqlCodegenService2 build
• gradle clean graphqlCodegenService1 graphqlCodegenService2 build

Convert generated Java classes to Kotlin classes

1. Navigate in IntelliJ IDEA to the ./build/generated/graphql/ folder and press Cmd+Alt+Shift+K
2. Access generated classes as normal Kotlin classes.

Inspired by

swagger-codegen