Support option input values in client requests

This commit adds support for optional input values in GraphQL client
requests, using `ArgumentValue<T>`.
This commit adds new Jackson 3.x and 2.x modules that support the
serialisation of `ArgumentValue<T>` in input types. Note that this is
not meant to be used on the server side, and deserialization is not
supported.

Closes gh-1264

Author: bclozel

spring-graphql-docs/build.gradle

@@ -27,6 +27,7 @@ dependencies {
 	implementation 'com.querydsl:querydsl-core'
 	implementation "org.springframework.boot:spring-boot-starter-graphql:${springBootVersion}"
 	implementation "org.springframework.boot:spring-boot-starter-web:${springBootVersion}"
+	implementation 'tools.jackson.core:jackson-databind'
 	implementation 'io.rsocket:rsocket-core'
 	implementation 'io.rsocket:rsocket-transport-netty'
 	implementation('com.netflix.graphql.dgs.codegen:graphql-dgs-codegen-shared-core') {

spring-graphql-docs/modules/ROOT/pages/client.adoc

@@ -393,6 +393,49 @@ include-code::UseInterceptor[tag=register,indent=0]
 
 
 
+[[client.argumentvalue]]
+== Optional input
+
+By default, input types in GraphQL are nullable and optional.
+An input value (or any of its fields) can be set to the `null` literal, or not provided at all.
+This distinction is useful for partial updates with a mutation where the underlying data may also be,
+either set to `null` or not changed at all accordingly.
+
+Similar to the xref:controllers.adoc#controllers.schema-mapping.argument-value[`ArgumentValue<T> support in controllers`],
+we can wrap an Input type with `ArgumentValue<T>` or use it at the level of class attributes on the client side.
+Given a `ProjectInput` class like:
+
+include-code::ProjectInput[indent=0]
+
+We can use our client to send a mutation request:
+
+include-code::ArgumentValueClient[tag=argumentvalue,indent=0]
+<1> we can use `ArgumentValue.omitted()` instead, to ignore this field
+
+For this to work, the client must use Jackson for JSON (de)serialization and must be configured
+with the `org.springframework.graphql.client.json.GraphQlJacksonModule`.
+This can be registered manually on the underlying HTTP client like so:
+
+include-code::ArgumentValueClient[tag=createclient,indent=0]
+
+This `GraphQlJacksonModule` can be globally registered in Spring Boot applications by contributing it as a bean:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+    @Configuration
+    public class GraphQlJsonConfiguration {
+
+    	@Bean
+    	public GraphQlJacksonModule graphQLModule() {
+    		return new GraphQlJacksonModule();
+    	}
+
+    }
+----
+
+NOTE: Jackson 2.x support is also available with the `GraphQlJackson2Module`.
+
+
 [[client.dgsgraphqlclient]]
 == DGS Codegen
 

spring-graphql-docs/modules/ROOT/pages/controllers.adoc

@@ -440,6 +440,9 @@ For example:
 method parameter, either initialized via a constructor argument or via a setter, including
 as a field of an object nested at any level below the top level object.
 
+This is also supported on the client side with a dedicated Jackson Module,
+see the xref:client.adoc#client.argumentvalue[`ArgumentValue` support for clients] section.
+
 
 [[controllers.schema-mapping.arguments]]
 === `@Arguments`

spring-graphql-docs/src/main/java/org/springframework/graphql/docs/client/argumentvalue/ArgumentValueClient.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2020-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.graphql.docs.client.argumentvalue;
+
+import java.util.Map;
+
+import tools.jackson.databind.json.JsonMapper;
+
+import org.springframework.graphql.client.ClientGraphQlResponse;
+import org.springframework.graphql.client.HttpGraphQlClient;
+import org.springframework.graphql.client.json.GraphQlJacksonModule;
+import org.springframework.graphql.data.ArgumentValue;
+import org.springframework.http.codec.json.JacksonJsonEncoder;
+import org.springframework.web.reactive.function.client.WebClient;
+
+public class ArgumentValueClient {
+
+	private final HttpGraphQlClient graphQlClient;
+
+	// tag::createclient[]
+	public ArgumentValueClient(HttpGraphQlClient graphQlClient) {
+		JsonMapper jsonMapper = JsonMapper.builder().addModule(new GraphQlJacksonModule()).build();
+		JacksonJsonEncoder jsonEncoder = new JacksonJsonEncoder(jsonMapper);
+		WebClient webClient = WebClient.builder()
+				.baseUrl("https://example.com/graphql")
+				.codecs((codecs) -> codecs.defaultCodecs().jacksonJsonEncoder(jsonEncoder))
+				.build();
+		this.graphQlClient = HttpGraphQlClient.create(webClient);
+	}
+	// end::createclient[]
+
+	// tag::argumentvalue[]
+	public void updateProject() {
+		ProjectInput projectInput = new ProjectInput("spring-graphql",
+				ArgumentValue.ofNullable("Spring for GraphQL")); // <1>
+		ClientGraphQlResponse response = this.graphQlClient.document("""
+						mutation updateProject($project: ProjectInput!) {
+							  updateProject($project: $project) {
+								id
+								name
+							  }
+						}
+						""")
+				.variables(Map.of("project", projectInput))
+				.executeSync();
+	}
+	// end::argumentvalue[]
+}

spring-graphql-docs/src/main/java/org/springframework/graphql/docs/client/argumentvalue/ProjectInput.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2020-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.graphql.docs.client.argumentvalue;
+
+
+import org.springframework.graphql.data.ArgumentValue;
+
+public record ProjectInput(String id, ArgumentValue<String> name) {
+
+}

spring-graphql/src/main/java/org/springframework/graphql/client/AbstractGraphQlClientBuilder.java

@@ -24,19 +24,26 @@
 import java.util.function.Consumer;
 
 import org.jspecify.annotations.Nullable;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.json.JsonMapper;
 
 import org.springframework.core.codec.Decoder;
 import org.springframework.core.codec.Encoder;
 import org.springframework.core.io.ClassPathResource;
+import org.springframework.graphql.MediaTypes;
 import org.springframework.graphql.client.GraphQlClientInterceptor.Chain;
 import org.springframework.graphql.client.GraphQlClientInterceptor.SubscriptionChain;
+import org.springframework.graphql.client.json.GraphQlJackson2Module;
+import org.springframework.graphql.client.json.GraphQlJacksonModule;
 import org.springframework.graphql.support.CachingDocumentSource;
 import org.springframework.graphql.support.DocumentSource;
 import org.springframework.graphql.support.ResourceDocumentSource;
+import org.springframework.http.MediaType;
 import org.springframework.http.codec.json.Jackson2JsonDecoder;
 import org.springframework.http.codec.json.Jackson2JsonEncoder;
 import org.springframework.http.codec.json.JacksonJsonDecoder;
 import org.springframework.http.codec.json.JacksonJsonEncoder;
+import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 
@@ -47,7 +54,7 @@
  *
  * <p>Subclasses must implement {@link #build()} and call
  * {@link #buildGraphQlClient(GraphQlTransport)} to obtain a default, transport
- * agnostic {@code GraphQlClient}. A transport specific extension can then wrap
+ * agnostic {@code GraphQlClient}. A transport-specific extension can then wrap
  * this default tester by extending {@link AbstractDelegatingGraphQlClient}.
  *
  * @param <B> the type of builder
@@ -241,25 +248,31 @@ private Decoder<?> getDecoder() {
 
 	protected static class DefaultJacksonCodecs {
 
+		private static final ObjectMapper JSON_MAPPER = JsonMapper.builder()
+				.addModule(new GraphQlJacksonModule()).build();
+
 		static Encoder<?> encoder() {
-			return new JacksonJsonEncoder();
+			return new JacksonJsonEncoder(JSON_MAPPER, MediaType.APPLICATION_JSON);
 		}
 
 		static Decoder<?> decoder() {
-			return new JacksonJsonDecoder();
+			return new JacksonJsonDecoder(JSON_MAPPER, MediaType.APPLICATION_JSON, MediaTypes.APPLICATION_GRAPHQL_RESPONSE);
 		}
 
 	}
 
 	@SuppressWarnings("removal")
 	protected static class DefaultJackson2Codecs {
 
+		private static final com.fasterxml.jackson.databind.ObjectMapper JSON_MAPPER =
+				Jackson2ObjectMapperBuilder.json().modulesToInstall(new GraphQlJackson2Module()).build();
+
 		static Encoder<?> encoder() {
-			return new Jackson2JsonEncoder();
+			return new Jackson2JsonEncoder(JSON_MAPPER, MediaType.APPLICATION_JSON);
 		}
 
 		static Decoder<?> decoder() {
-			return new Jackson2JsonDecoder();
+			return new Jackson2JsonDecoder(JSON_MAPPER, MediaType.APPLICATION_JSON, MediaTypes.APPLICATION_GRAPHQL_RESPONSE);
 		}
 	}
 

spring-graphql/src/main/java/org/springframework/graphql/client/AbstractGraphQlClientSyncBuilder.java

@@ -25,16 +25,20 @@
 import org.jspecify.annotations.Nullable;
 import reactor.core.scheduler.Scheduler;
 import reactor.core.scheduler.Schedulers;
+import tools.jackson.databind.json.JsonMapper;
 
 import org.springframework.core.codec.Decoder;
 import org.springframework.core.codec.Encoder;
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.graphql.GraphQlResponse;
 import org.springframework.graphql.client.SyncGraphQlClientInterceptor.Chain;
+import org.springframework.graphql.client.json.GraphQlJackson2Module;
+import org.springframework.graphql.client.json.GraphQlJacksonModule;
 import org.springframework.graphql.support.CachingDocumentSource;
 import org.springframework.graphql.support.DocumentSource;
 import org.springframework.graphql.support.ResourceDocumentSource;
 import org.springframework.http.converter.HttpMessageConverter;
+import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;
 import org.springframework.http.converter.json.JacksonJsonHttpMessageConverter;
 import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
 import org.springframework.util.Assert;
@@ -197,15 +201,18 @@ private HttpMessageConverter<Object> getJsonConverter() {
 	private static final class DefaultJacksonConverter {
 
 		static HttpMessageConverter<Object> initialize() {
-			return new JacksonJsonHttpMessageConverter();
+			JsonMapper jsonMapper = JsonMapper.builder().addModule(new GraphQlJacksonModule()).build();
+			return new JacksonJsonHttpMessageConverter(jsonMapper);
 		}
 	}
 
 	@SuppressWarnings("removal")
 	private static final class DefaultJackson2Converter {
 
 		static HttpMessageConverter<Object> initialize() {
-			return new MappingJackson2HttpMessageConverter();
+			com.fasterxml.jackson.databind.ObjectMapper objectMapper = Jackson2ObjectMapperBuilder.json()
+					.modulesToInstall(new GraphQlJackson2Module()).build();
+			return new MappingJackson2HttpMessageConverter(objectMapper);
 		}
 	}