Skip to the content.

Codegen 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. See graphqlSchemas
graphqlQueryIntrospectionResu
ltPath
String None Path to GraphQL Introspection Query result in json format (with root object __schema or data.__schema). Sample: sample-introspection-query-result.json
outputDir String None The output target directory into which code will be generated.
configurationFiles List(String) Empty Paths to the files with mapping configurations. Supported formats. JSON, HOCON. Order of specified configuration files matters, so the default configuration should be placed at the end.
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.
generateDataFetchingEnvironme
ntArgumentInApis
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.
generateParameterizedFieldsResolvers Boolean True Specifies whether separate Resolver interface for parametrized fields should be generated. If false, then add parametrized field to the type definition and ignore field parameters. If true then separate Resolver interface for parametrized fields will be generated.
generateImmutableModels Boolean False Specifies whether generated model classes should be immutable.
generateToString Boolean False Specifies whether generated model classes should have toString method defined.
generateJacksonTypeIdResolver Boolean False Specifies whether generated union interfaces should be annotated with a custom Jackson type id resolver generated in model package.
addGeneratedAnnotation Boolean True Specifies whether generated classes should have @Generated annotation.
generatedAnnotation String jakarta.annotation.Generated
javax.annotation.Generated
Qualified class name (with package) of the @Generated annotation that will be added on top of every generated class (if addGeneratedAnnotation is true)
apiNamePrefix String Empty Sets the prefix for GraphQL api classes (query, mutation, subscription).
apiNameSuffix String Resolver Sets the suffix for GraphQL api classes (query, mutation, subscription).
apiInterfaceStrategy See
ApiInterfaceStrategy
INTERFACE_PER_OPERATION See ApiInterfaceStrategy
apiRootInterfaceStrategy See
ApiRootInterfaceStrategy
SINGLE_INTERFACE See ApiRootInterfaceStrategy
apiNamePrefixStrategy See
ApiNamePrefixStrategy
CONSTANT See ApiNamePrefixStrategy
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.
typeResolverPrefix String Empty Sets the prefix for GraphQL type resolver classes.
typeResolverSuffix String Resolver Sets the suffix for GraphQL type resolver classes.
customTypesMapping Map(String,String) Empty See CustomTypesMapping
customTemplatesRoot File Project’s dir Use to supply the path the to custom FreeMarker templates root directory.
customTemplates Map(String,String) Empty Use to supply paths to custom FreeMarker templates for code generation.
customAnnotationsMapping Map(String,String[]) Empty See CustomAnnotationsMapping
directiveAnnotationsMapping Map(String,String[]) Empty See DirectiveAnnotationsMapping
fieldsWithResolvers Set(String) Empty Fields that require Resolvers should be defined here in format: TypeName.fieldName or TypeName or @directive. E.g.: Person, Person.friends, @customResolver.
fieldsWithoutResolvers Set(String) Empty Fields that DO NOT require Resolvers should be defined here in format: TypeName.fieldName or TypeName or @directive. Can be used in conjunction with generateExtensionFieldsResolvers option. E.g.: Person, Person.friends, @noResolver.
fieldsToExcludeFromGeneration Set(String) Empty Fields to exclude from generation should be defined here in format: TypeName.fieldName.
resolverArgumentAnnotations Set(String) Empty Annotations that will be added to all resolver arguments. Can be used for spring-graphql inegration by supplying: org.springframework.graphql.data.method.annotation.Argument
parametrizedResolverAnnotations Set(String) Empty Annotations that will be added to all parametrized resolver methods. Can be used for spring-graphql inegration by supplying: org.springframework.graphql.data.method.annotation.SchemaMapping(typeName="")
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.
generateModelsForRootTypes Boolean False Specifies whether model classes should be generated for type Query, type Subscription, type Mutation.
useOptionalForNullableReturnTypes Boolean False Specifies whether nullable return types of api methods should be wrapped into java.util.Optional<>. Lists will not be wrapped.
useWrapperForNullableInputTypes Boolean False Specifies whether nullable parameters on input types should be wrapped into ArgumentValue<>. This requires org.springframework.graphql.data version 1.1.0+. Lists will not be wrapped.
generateApisWithThrowsException Boolean True Specifies whether api interface methods should have throws Exception in signature.
generateApisWithSuspendFunctions Boolean False Specifies whether api interface methods should have suspend modifier in signature. Only supported in Kotlin.
generateNoArgsConstructorOnly Boolean False Specifies whether model classes should only have a no-args constructor. All-args constructor will not be generated in case value is true
generateModelsWithPublicFields Boolean False Specifies whether model classes should have public fields and NO getters/setters. By default, fields are private and there are getters/setters for each field.
apiReturnType String Empty Return type for api methods (query/mutation). For example: reactor.core.publisher.Mono, etc.
apiReturnListType String Empty Return type for api methods (query/mutation) having list type. For example: reactor.core.publisher.Flux, etc. By default is empty, so apiReturnType will be used.
subscriptionReturnType String Empty Return type for subscription methods. For example: org.reactivestreams.Publisher, io.reactivex.Observable, etc.
relayConfig See
RelayConfig
@connection(for: ...) See RelayConfig
generateClient Boolean False Specifies whether client-side classes should be generated for each query, mutation and subscription. This includes: Request classes (contain input data), ResponseProjection classes for each type (contain response fields) and Response classes (contain response data).
requestSuffix String Request Sets the suffix for Request classes.
responseSuffix String Response Sets the suffix for Response 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). See parentInterfaces
generateAllMethodInProjection Boolean True Enables whether the all$() method should be generated in the projection classes. Disabling enforces the client to select the fields manually.
responseProjectionMaxDepth Integer 3 Sets max depth when use all$() which for facilitating the construction of projection automatically, the fields on all projections are provided when it be invoked. This is a global configuration, of course, you can use all$(max) to set for each method. For self recursive types, too big depth may result in a large number of returned data!
generatedLanguage Enum GeneratedLanguage.JAVA Choose which language you want to generate, Java,Scala,Kotlin were supported. Note that due to language features, there are slight differences in default values between languages.
generateModelOpenClasses Boolean False The class type of the generated model. If true, generate normal classes, else generate data classes. It only support in kotlin(data class) and scala(case class). Maybe we will consider to support Java record in the future.
initializeNullableTypes Boolean False Adds a default null value to nullable arguments. Only supported in Kotlin.
generateSealedInterfaces Boolean False This applies to generated interfaces on unions and interfaces. If true, generate sealed interfaces, else generate normal ones. It is only supported in Kotlin and Scala.
typesAsInterfaces Set(String) Empty Types that must generated as interfaces should be defined here in format: TypeName or @directive. E.g.: User, @asInterface.
fieldsWithDataFetcherResult Set(String) Empty Types that must have DataFetchResult should be defined here in format: TypeName, or TypeName.fieldName or @directive. E.g.: Item, Item.items or @dataFetcherResult.
useObjectMapperForRequestSerialization Set(String) Empty Fields that require serialization using com.fasterxml.jackson.databind.ObjectMapper#writeValueAsString(Object). Values should be defined here in the following format: GraphqlObjectName.fieldName or GraphqlTypeName. If just type is specified, then all fields of this type will be serialized using ObjectMapper. E.g.: ["Person.createdDateTime", ZonedDateTime"]
supportUnknownFields Boolean False Specifies whether api classes should support unknown fields during serialization or deserialization. If true, classes will include a property of type java.util.Map<String,Object> that will store unknown fields.
unknownFieldsPropertyName String userDefinedFields Specifies the name of the property to be included in api classes to support unknown fields during serialization or deserialization
skip Boolean False If true, then code generation will not happen
skipSchemaSizeLimit Boolean True When set to true, the GraphQL schema will be processed with token, character, line and rule depth limits. Set to false to process the schema regardless of its size.
       

Option graphqlSchemas

When exact paths to GraphQL schemas are too cumbersome to provide in the graphqlSchemaPaths, use the 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 ApiInterfaceStrategy

Defines how to generate interfaces (resolvers) for each operation: Query/Mutation/Subscription. Provides ability to skip generation of separate interface class for each operation in favor of having a single “root” interface ( see ApiRootInterfaceStrategy and ApiNamePrefixStrategy)

Value Description
INTERFACE_PER_OPERATION (default) Generate separate interface classes for each GraphQL operation.
DO_NOT_GENERATE Do not generate separate interfaces classes for GraphQL operation.

Option ApiRootInterfaceStrategy

Defines how root interface (QueryResolver / MutationResolver / SubscriptionResolver will be generated (in addition to separate interfaces for each query/mutation/subscription)

Value Description
INTERFACE_PER_SCHEMA Generate multiple super-interfaces for each graphql file.
Takes into account apiNamePrefixStrategy.
E.g.: OrderServiceQueryResolver.java, ProductServiceQueryResolver.java, etc.
SINGLE_INTERFACE (default) Generate a single QueryResolver.java, MutationResolver.java, SubscriptionResolver.java for all graphql schema files.
DO_NOT_GENERATE Do not generate super interface for GraphQL operations.

Option ApiNamePrefixStrategy

Defines which prefix to use for API interfaces.

Value Description
FILE_NAME_AS_PREFIX Will take GraphQL file name as a prefix for all generated API interfaces + value of apiNamePrefix config option.
E.g.:
* following schemas: resources/schemas/order-service.graphql, resources/schemas/product-service.graphql
* will result in: OrderServiceQueryResolver.java, ProductServiceQueryResolver.java, etc
FOLDER_NAME_AS_PREFIX Will take parent folder name as a prefix for all generated API interfaces + value of apiNamePrefix config option. E.g.:
* following schemas: resources/order-service/schema1.graphql, resources/order-service/schema2.graphql
* will result in: OrderServiceQueryResolver.java, OrderServiceGetOrderByIdQueryResolver.java, etc
CONSTANT (default) Will take only the value of apiNamePrefix config option.

resources/schemas/order-service.graphql, * resources/schemas/product-service.graphql
* will result in: OrderServiceQueryResolver.java , ProductServiceQueryResolver.java, etc | | FOLDER_NAME_AS_PREFIX | Will take parent folder name as a prefix for all generated API interfaces + value of apiNamePrefix config option. E.g.:
* following schemas: * resources/order-service/schema1.graphql, * resources/order-service/schema2.graphql
* will result in: OrderServiceQueryResolver.java , OrderServiceGetOrderByIdQueryResolver.java, etc | | CONSTANT (default) | Will take only the value of apiNamePrefix config option. |

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 `` placeholder. E.g.: graphql.kickstart.tools.GraphQLResolver<>

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.

Option customTypesMapping

Can be used to supply custom mappings for scalars.

Supports following formats:

Option customAnnotationsMapping

Can be used to supply custom annotations (serializers) for scalars. @ in front of the annotation class is optional.

Supports following formats:

Option directiveAnnotationsMapping

Can be used to supply custom annotations for directives in a following format: Map of (GraphQL.directiveName) to (JavaAnnotation). E.g.: auth = @org.springframework.security.access.annotation.Secured(). @ in front of the annotation class is optional.

Note: In order to supply the value of directive argument to annotation, use placeholder . You can also use one of the formatters for directive argument value:, ,.

Option relayConfig

Can be used to supply a custom configuration for Relay support. For reference see: https://www.graphql-java-kickstart.com/tools/relay/

Key inside relayConfig Data Type Default value Description
directiveName String connection Directive name used for marking a field.
directiveArgumentName String for Directive argument name that contains a GraphQL type name.
connectionType String graphql.relay.Connection Generic Connection type.

For example, the following schema:

type Query { users(first: Int, after: String): UserConnection @connection(for: "User") }

will result in generating the interface with the following method:

graphql.relay.Connection<User> users(Integer first, String after) throws Exception;

External mapping configuration

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

JSON:

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

HOCON:

generateClient=true
generateApis=true
generateBuilder=true
generateImmutableModels=true
generateToString=true
generateEqualsAndHashCode=true
apiPackageName="io.github.graphql.j.resolver"
modelPackageName="io.github.graphql.j.model"
modelNameSuffix="TO"
apiInterfaceStrategy="DO_NOT_GENERATE"
apiRootInterfaceStrategy="SINGLE_INTERFACE"
generateModelsForRootTypes=true
apiNamePrefix="GitHub"
addGeneratedAnnotation=false
generatedLanguage="KOTLIN"
customTypesMapping={
    Long="Long",
    Object="org.json.JSONObject"
}
customAnnotationsMapping={
    "QuestionNode.metaData"=["com.fasterxml.jackson.databind.annotation.JsonDeserialize(using = com.github.dreamylost.JsonObjectDeserializer::class)"]
    "QuestionNode.envInfo"=["com.fasterxml.jackson.databind.annotation.JsonDeserialize(using = com.github.dreamylost.JsonObjectDeserializer::class)"]
}