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
graphqlQueryIntrospectionResultPath	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.
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.
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.
generateImmutableModels	Boolean	False	Specifies whether generated model classes should be immutable.
generateToString	Boolean	False	Specifies whether generated model classes should have toString method defined.
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
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.
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.
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
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!

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.

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 jsonConfigurationFile Sample content of the file:

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