codegen-options.md

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="{{TYPE_NAME}}")
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 {{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.

Option customTypesMapping

Can be used to supply custom mappings for scalars.

Supports following formats:

• Map of (GraphQLObjectName.fieldName) to (JavaType). E.g.: Event.dateTime = java.util.Date
• Map of (GraphQLType) to (JavaType). E.g.: EpochMillis = java.time.LocalDateTime

Option customAnnotationsMapping

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

Supports following formats:

• Map of (GraphQLObjectName.fieldName) to (JavaAnnotation). E.g.: Event.dateTime = @com.fasterxml.jackson.databind.annotation.JsonDeserialize(using = com.example.DateDeserializer.class)
• Map of (GraphQLType) to (JavaAnnotation). E.g.: EpochMillis = @com.fasterxml.jackson.databind.annotation.JsonDeserialize(using = com.example.EpochMillisDeserializer.class)

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({{roles}}). @ in front of the annotation class is optional.

Note: In order to supply the value of directive argument to annotation, use placeholder {{directiveArgument}}. You can also use one of the formatters for directive argument value: {{val?toString}}, {{val?toArray}} , {{val?toArrayOfStrings}}.

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)"]
}