Add documentation for GraphQL support (#3756)

* Add documentation for GraphQL support

* * Fix to the latest Spring for GraphQL
* Mention in the doc an `ExecutionGraphQlRequest` as a request message payload

src/reference/asciidoc/endpoint-summary.adoc

@@ -84,6 +84,12 @@ The following table summarizes the various endpoints with quick links to the app
 | N
 | N
 
+| *GraphQL*
+| N
+| N
+| N
+| <<./graphql.adoc#graphql-outbound-gateway,GraphQL Outbound Gateway>>
+
 | *HTTP*
 | <<./http.adoc#http-namespace,HTTP Namespace Support>>
 | <<./http.adoc#http-namespace,HTTP Namespace Support>>

src/reference/asciidoc/graphql.adoc

@@ -1,7 +1,8 @@
 [[graphql]]
 == GraphQL Support
 
-Spring Integration provides support for GraphQL.
+Spring Integration provides channel adapters for interaction with https://graphql.org/[GraphQL] protocol.
+The implementation is based on the https://spring.io/projects/spring-graphql[Spring for GraphQL].
 
 You need to include this dependency into your project:
 
@@ -21,3 +22,84 @@ You need to include this dependency into your project:
 compile "org.springframework.integration:spring-integration-graphql:{project-version}"
 ----
 ====
+
+[[graphql-outbound-gateway]]
+=== GraphQL Outbound Gateway
+
+The `GraphQlMessageHandler` is an `AbstractReplyProducingMessageHandler` extension representing an outbound gateway contract to perform GraphQL `query`, `mutation` or `subscription` operation and produce their result.
+It requires a `org.springframework.graphql.ExecutionGraphQlService` for execution of `operation`, which can be configured statically or via SpEL expression against a request message.
+The `operationName` is optional and also can be configured statically or via SpEL expression.
+The `variablesExpression` is also optional and used for parametrized operations.
+The `locale` is optional and used for operation execution context in the https://www.graphql-java.com/[GraphQL Java] library.
+The `executionId` can be configured via SpEL expression and defaults to `id` header of the request message.
+
+If the payload of request message is an instance of `ExecutionGraphQlRequest`, then there's no any setup actions are performed in the `GraphQlMessageHandler` and such an input is used as is for the `ExecutionGraphQlService.execute()`.
+Otherwise, the `operation`, `operationName`, `variables` and `executionId` are determined against request message using SpEL expressions mentioned above.
+
+The `GraphQlMessageHandler` is a reactive streams component and produces a `Mono<ExecutionGraphQlResponse>` reply as a result of the `ExecutionGraphQlService.execute(ExecutionGraphQlRequest)`.
+Such a `Mono` is subscribed by the framework in the `ReactiveStreamsSubscribableChannel` output channel or in the `AbstractMessageProducingHandler` asynchronously when the output channel is not reactive.
+See documentation for the `ExecutionGraphQlResponse` how to process the GraphQL operation result.
+
+====
+[source, java]
+----
+@Bean
+GraphQlMessageHandler handler(ExecutionGraphQlService graphQlService) {
+    GraphQlMessageHandler graphQlMessageHandler = new GraphQlMessageHandler(graphQlService);
+    graphQlMessageHandler.setOperation("""
+            query HeroNameAndFriends($episode: Episode) {
+              hero(episode: $episode) {
+                name
+                friends {
+                  name
+                }
+              }
+            }""");
+    graphQlMessageHandler.setVariablesExpression(new SpelExpressionParser().parseExpression("{episode:'JEDI'}"));
+    return graphQlMessageHandler;
+}
+
+@Bean
+IntegrationFlow graphqlQueryMessageHandlerFlow(GraphQlMessageHandler handler) {
+    return IntegrationFlows.from(MessageChannels.flux("inputChannel"))
+            .handle(handler)
+            .channel(c -> c.flux("resultChannel"))
+            .get();
+}
+
+@Bean
+ExecutionGraphQlService graphQlService(GraphQlSource graphQlSource) {
+    return new DefaultExecutionGraphQlService(graphQlSource);
+}
+
+@Bean
+GraphQlSource graphQlSource(AnnotatedControllerConfigurer annotatedDataFetcherConfigurer) {
+    return GraphQlSource.builder()
+            .schemaResources(new ClassPathResource("graphql/test-schema.graphqls"))
+            .configureRuntimeWiring(annotatedDataFetcherConfigurer)
+            .build();
+}
+
+@Bean
+AnnotatedControllerConfigurer annotatedDataFetcherConfigurer() {
+    return new AnnotatedControllerConfigurer();
+}
+----
+====
+
+The special treatment should be applied for the result of a subscription operation.
+In this case the `RequestOutput.getData()` returns a `SubscriptionPublisher` which has to subscribed and processed manually.
+Or it can be flat-mapped via plain service activator to the reply for the `FluxMessageChannel`:
+
+====
+[source, java]
+----
+@ServiceActivator(inputChannel = "graphQlResultChannel", outputChannel="graphQlSubscriptionChannel")
+public SubscriptionPublisher obtainSubscriptionResult(RequestOutput output) {
+	return output.getData(0);
+}
+----
+====
+
+Such an outbound gateway can be used not only for GraphQL request via HTTP, but from any upstream endpoint which produces or carries a GraphQL operation or its arguments in the message.
+The result of the `GraphQlMessageHandler` handling can be produces as a reply to the upstream request or sent downstream for further processing in the integration flow.

src/reference/asciidoc/reactive-streams.adoc

@@ -326,7 +326,7 @@ public class MainFlow {
 ----
 ====
 
-Currently, Spring Integration provides channel adapter (or gateway) implementations for <<./webflux.adoc#webflux,WebFlux>>, <<./rsocket.adoc#rsocket,RSocket>>, <<./mongodb.adoc#mongodb,MongoDb>>, <<./r2dbc.adoc#r2dbc,R2DBC>>, <<./zeromq.adoc#zeromq,ZeroMQ>>.
+Currently, Spring Integration provides channel adapter (or gateway) implementations for <<./webflux.adoc#webflux,WebFlux>>, <<./rsocket.adoc#rsocket,RSocket>>, <<./mongodb.adoc#mongodb,MongoDb>>, <<./r2dbc.adoc#r2dbc,R2DBC>>, <<./zeromq.adoc#zeromq,ZeroMQ>>, <<./graphql.adoc#graphql,GraphQL>>.
 The <<./redis.adoc#redis-stream-outbound,Redis Stream Channel Adapters>> are also reactive and uses `ReactiveStreamOperations` from Spring Data.
 Also, an https://github.com/spring-projects/spring-integration-extensions/tree/main/spring-integration-cassandra[Apache Cassandra Extension] provides a `MessageHandler` implementation for the Cassandra reactive driver.
 More reactive channel adapters are coming, for example for Apache Kafka in <<./kafka.adoc#kafka,Kafka>> based on the `ReactiveKafkaProducerTemplate` and `ReactiveKafkaConsumerTemplate` from https://spring.io/projects/spring-kafka[Spring for Apache Kafka] etc.