# 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](#option-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](#option-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](../src/test/resources/introspection-result/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](#option-apiinterfacestrategy)* | `INTERFACE_PER_OPERATION` | *See [ApiInterfaceStrategy](#option-apiinterfacestrategy)* |
| `apiRootInterfaceStrategy` | *See
[ApiRootInterfaceStrategy](#option-apirootinterfacestrategy)* | `SINGLE_INTERFACE` | *See [ApiRootInterfaceStrategy](#option-apirootinterfacestrategy)* |
| `apiNamePrefixStrategy` | *See
[ApiNamePrefixStrategy](#option-apinameprefixstrategy)* | `CONSTANT` | *See [ApiNamePrefixStrategy](#option-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](#option-customtypesmapping)* |
| `customTemplates` | Map(String,String) | Empty | Use to supply paths to custom FreeMarker templates for code generation. |
| `customAnnotationsMapping` | Map(String,String[]) | Empty | *See [CustomAnnotationsMapping](#option-customannotationsmapping)* |
| `directiveAnnotationsMapping` | Map(String,String[]) | Empty | *See [DirectiveAnnotationsMapping](#option-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`. |
| `resolverArgumentAnnotations` | Set(String) | Empty | Annotations that will be added to all resolver arguments. Can be used for [spring-graphql](https://github.com/spring-projects/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](https://github.com/spring-projects/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<>`](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Optional.html). Lists will not be wrapped. |
| `generateApisWithThrowsException` | Boolean | True | Specifies whether api interface methods should have `throws Exception` in signature. |
| `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](#option-relayconfig)* | `@connection(for: ...)` | *See [RelayConfig](#option-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](#option-parentinterfaces)* | Empty | Block to define parent interfaces for generated interfaces (query / mutation / subscription / type resolver). *See [parentInterfaces](#option-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`. |
| `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`](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Map.html) 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 |
### 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](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) 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](#option-apirootinterfacestrategy)*
and *[ApiNamePrefixStrategy](#option-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](https://github.com/graphql-java-kickstart/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 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:
```json
{
"generateApis": true,
"packageName": "com.kobylynskyi.graphql.testconfigjson",
"customTypesMapping": {
"Price.amount": "java.math.BigDecimal"
}
}
```
[HOCON](https://en.wikipedia.org/wiki/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)"]
}
```