Add possible Gradle options in the doc (#5124)

Author: martinbonnin

docs/source/advanced/plugin-configuration.mdx

@@ -2,13 +2,15 @@
 title: Gradle plugin configuration
 ---
 
-Apollo Kotlin's default configuration works for the majority of use cases. If you're getting started, see the [getting started guide](../) for an overview of the default Gradle configuration.
+Apollo Kotlin's default configuration works for the majority of use cases. If you're getting started, see
+the [getting started guide](../) for an overview of the default Gradle configuration.
 
 This article describes configuration options for advanced use cases when using Gradle.
 
 ## Using multiple GraphQL APIs
 
-Apollo Kotlin supports communicating with multiple GraphQL endpoints with different schemas. To do so, create multiple services like so:
+Apollo Kotlin supports communicating with multiple GraphQL endpoints with different schemas. To do so, create multiple
+services like so:
 
 ```kotlin
 apollo {
@@ -39,9 +41,11 @@ apollo {
 
 ## Combining multiple schema files
 
-Apollo Kotlin supports a collection of client directives, including `@nonnull`, `@optional`, and `@typePolicy`. These directives enable you to extend your server's base schema with client-specific types and fields.
+Apollo Kotlin supports a collection of client directives, including `@nonnull`, `@optional`, and `@typePolicy`. These
+directives enable you to extend your server's base schema with client-specific types and fields.
 
-If you expand your schema in a separate file, you can instruct Apollo Kotlin to construct its schema from a combination of multiple files, like so:
+If you expand your schema in a separate file, you can instruct Apollo Kotlin to construct its schema from a combination
+of multiple files, like so:
 
 ```kotlin
 apollo {
@@ -61,7 +65,8 @@ By default, Apollo Kotlin adds generated source:
 - to `commonMain` for multiplatform projects
 - to all non-test variants for Android projects
 
-You can customize this behavior with the `outputDirConnection` property. For example, to wire a service to the test source set of a Kotlin
+You can customize this behavior with the `outputDirConnection` property. For example, to wire a service to the test
+source set of a Kotlin
 JVM project:
 
 ```kotlin
@@ -76,7 +81,8 @@ apollo {
 
 ## Android variants support
 
-It is sometimes useful to have different operations or schemas depending on the [variant](https://developer.android.com/studio/build/build-variants) of your Android project.
+It is sometimes useful to have different operations or schemas depending on
+the [variant](https://developer.android.com/studio/build/build-variants) of your Android project.
 
 To do this, you can instruct the Gradle plugin to automatically configure a Service per variant, like so:
 
@@ -89,10 +95,13 @@ apollo {
 }
 ```
 
-- `sourceFolder` where to find the GraphQL relative to "src/$sourceSetName/graphql". Pass "." to look into "src/$sourceSetName/graphql".
+- `sourceFolder` where to find the GraphQL relative to "src/$sourceSetName/graphql". Pass "." to look into "
+  src/$sourceSetName/graphql".
 - `nameSuffix` a suffix to use for the service name. Leave blank to use the variant name as is.
 
-Similarly to what the Android variant system does with source code, the GraphQL files are handled additively, and files in `src/main/graphql` are included in all services. This means your project could look like this (e.g. when certain operations must only exist in debug builds):
+Similarly to what the Android variant system does with source code, the GraphQL files are handled additively, and files
+in `src/main/graphql` are included in all services. This means your project could look like this (e.g. when certain
+operations must only exist in debug builds):
 
 ```
 - main
@@ -118,7 +127,8 @@ Or for instance like this (specific backend per flavor):
         - operations.graphql // Operations specific to the 'full' flavor
 ```
 
-If you have many variants and don't need to configure an Apollo Service for each one of them, it may be simpler to declare the Services manually, for instance:
+If you have many variants and don't need to configure an Apollo Service for each one of them, it may be simpler to
+declare the Services manually, for instance:
 
 ```kotlin
 apollo {
@@ -139,7 +149,6 @@ apollo {
 }
 ```
 
-
 ## Downloading a schema
 
 By default, the Gradle plugin registers a `downloadApolloSchema` task that you can use from the command line:
@@ -169,9 +178,11 @@ apollo {
 }
 ```
 
-This will create a task named `download<ServiceName>ApolloSchemaFromIntrospection` (`downloadServiceApolloSchemaFromIntrospection` by default).
+This will create a task
+named `download<ServiceName>ApolloSchemaFromIntrospection` (`downloadServiceApolloSchemaFromIntrospection` by default).
 
-If you register your schema with [Apollo Studio](https://www.apollographql.com/docs/studio/), use the `registry` block instead:
+If you register your schema with [Apollo Studio](https://www.apollographql.com/docs/studio/), use the `registry` block
+instead:
 
 ```kotlin
 apollo {
@@ -189,4 +200,152 @@ apollo {
 }
 ```
 
-This will create a task named `download<ServiceName>ApolloSchemaFromRegistry` (`downloadServiceApolloSchemaFromRegistry` by default).
+This will create a task named `download<ServiceName>ApolloSchemaFromRegistry` (`downloadServiceApolloSchemaFromRegistry`
+by default).
+
+## All options
+
+Below is a summary of the Gradle options in a single code block. For more details, take a look at the [ApolloExtension KDoc](https://www.apollographql.com/docs/kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo3.gradle.api/-apollo-extension/index.html)
+
+```kotlin
+apollo {
+  service("api") {
+    // The package name for the generated models
+    packageName.set("com.example")
+
+    // Adds the given directory as a GraphQL source root
+    srcDir("src/main/graphql")
+    // Operation files to include.
+    includes.add("**/*.graphql")
+    // Operation files to exclude.
+    excludes.add("**/*.graphqls")
+
+    // explicitly set the schema
+    schemaFile.set("src/main/graphql/schema.graphqls")
+    // you can also merge different files together
+    schemaFile.setFrom("shared/graphql/schema.graphqls", "shared/graphql/extra.graphqls")
+
+    // What codegen to use. One of "operationBased", "responseBased"
+    codegenModels.set("operationBased")
+
+    // Warn if using a deprecated field
+    warnOnDeprecatedUsages.set(true)
+    // Fail on warnings
+    failOnWarnings.set(true)
+
+    // Map the "Date" custom scalar to the com.example.Date Kotlin type
+    mapScalar("Date", "com.example.Date")
+    // Shorthands to map scalar to builtin types and configure their adapter at build time
+    mapScalarToUpload("Upload")
+    mapScalarToKotlinString("MyString")
+    mapScalarToKotlinInt("MyInt")
+    mapScalarToKotlinDouble("MyDouble")
+    mapScalarToKotlinFloat("MyFloat")
+    mapScalarToKotlinLong("MyLong")
+    mapScalarToKotlinBoolean("MyBoolean")
+    mapScalarToKotlinAny("MyAny")
+    mapScalarToJavaString("MyString")
+    mapScalarToJavaInteger("MyInteger")
+    mapScalarToJavaDouble("MyDouble")
+    mapScalarToJavaFloat("MyFloat")
+    mapScalarToJavaLong("MyLong")
+    mapScalarToJavaBoolean("MyBoolean")
+    mapScalarToJavaObject("MyObject")
+
+    // Configure operation ids for persisted queries
+    operationOutputGenerator = object : OperationOutputGenerator {
+      override fun generate(operationDescriptorList: Collection<OperationDescriptor>): OperationOutput {
+        return operationDescriptorList.map {
+          it.source.sha256() to it
+        }.toMap()
+      }
+
+      override val version = "v1"
+    }
+    // The format to output for the operation manifest.
+    operationManifestFormat.set("persistedQueryManifest")
+    // The file where to write the operaiton manifest
+    operationManifest.set("build/generated/persistedQueryManifest.json")
+
+    // Whether to generate Kotlin or Java models
+    generateKotlinModels.set(true)
+    // Target language version for the generated code.
+    languageVersion.set("1.5")
+    // Whether to suffix operation name with 'Query', 'Mutation' or 'Subscription'
+    useSemanticNaming.set(true)
+    // Whether to generate kotlin constructors with `@JvmOverloads` for more graceful Java interop experience when default values are present.
+    addJvmOverloads.set(true)
+    // Whether to generate Kotlin models with `internal` visibility modifier.
+    generateAsInternal.set(true)
+    // Whether to generate default implementation classes for GraphQL fragments.
+    generateFragmentImplementations.set(true)
+    // Whether to write the query document in models
+    generateQueryDocument.set(true)
+    // Whether to generate the Schema class.
+    generateSchema.set(true)
+    // Name for the generated schema
+    generatedSchemaName.set("Schema")
+    // Whether to generate operation variables as [com.apollographql.apollo3.api.Optional]
+    generateOptionalOperationVariables.set(true)
+    // Whether to generate the type safe Data builders.
+    generateDataBuilders.set(true)
+    // Whether to generate response model builders for Java.
+    generateModelBuilders.set(true)
+    // Whether to generate fields as primitive types (`int`, `double`, `boolean`) instead of their boxed types (`Integer`, `Double`, etc..)
+    generatePrimitiveTypes.set(true)
+    // The style to use for fields that are nullable in the Java generated code
+    nullableFieldStyle.set("apolloOptional")
+    // Whether to decapitalize field names in the generated models (for instance `FooBar` -> `fooBar`)
+    decapitalizeFields.set(false)
+
+    // Whether to add the [JsExport] annotation to generated models.
+    jsExport.set(true)
+    // When to add __typename.
+    addTypename.set("always")
+    // Whether to flatten the models. File paths are limited on MacOSX to 256 chars and flattening can help keeping the path length manageable
+    flattenModels.set(true)
+    // A list of [Regex] patterns for GraphQL enums that should be generated as Kotlin sealed classes instead of the default Kotlin enums.
+    sealedClassesForEnumsMatching.set(listOf(".*"))
+    // A list of [Regex] patterns for GraphQL enums that should be generated as Java classes.
+    classesForEnumsMatching.set(listOf(".*"))
+    // Whether fields with different shape are disallowed to be merged in disjoint types.
+    fieldsOnDisjointTypesMustMerge.set(false)
+
+
+    // The directory where the generated models will be written.
+    outputDir.set("build/generated/apollo")
+
+    // Whether to generate Apollo metadata. Apollo metadata is used for multi-module support.
+    generateApolloMetadata.set(true)
+    // list of [Regex] patterns matching for types and fields that should be generated whether they are used by queries/fragments in this module or not.
+    alwaysGenerateTypesMatching.set(listOf(".*"))
+    // Reuse the schema from an upstream module
+    dependsOn(project(":schema"))
+    // Compute used types from a downstream module 
+    isADependencyOf(project(":feature"))
+
+    // configure introspection schema download
+    introspection {
+      endpointUrl.set("https://your.domain/graphql/endpoint")
+      schemaFile.set(file("src/main/graphql/com/example/schema.graphqls"))
+    }
+    // configure registry schema download
+    registry {
+      key.set(System.getenv("APOLLO_KEY"))
+      graph.set(System.geten("APOLLO_GRAPH"))
+      schemaFile.set(file("src/main/graphql/com/example/schema.graphqls"))
+    }
+
+    // wire the generated models to the "test" source set
+    outputDirConnection {
+      connectToKotlinSourceSet("test")
+    }
+  }
+
+  // Make IDEA aware of codegen and will run it during your Gradle Sync, default: false
+  generateSourcesDuringGradleSync.set(true)
+
+  // Link sqlite for Kotlin native projects
+  linkSqlite.set(true)
+}
+```

docs/source/migration/3.0.mdx

@@ -107,7 +107,7 @@ The Gradle plugin has significantly changed in Apollo Kotlin 3.x to only generat
 
 #### `generateKotlinModels`
 
-Apollo Kotlin 3.0 generates Kotlin models by default. You can safely remove this behavior:
+If you are using the Kotlin Gradle Plugin, Apollo Kotlin 3.0 generates Kotlin models by default. You can safely remove this behavior:
 
 ```kotlin
 apollo {