From 779cc761ba0cdb55b0dc685a8e5b16f3301eb4ef Mon Sep 17 00:00:00 2001
From: rstoyanchev <rstoyanchev@vmware.com>
Date: Mon, 20 Nov 2023 21:37:57 +0000
Subject: [PATCH] Add reference docs section on codegen

Closes gh-847
---
 spring-graphql-docs/modules/ROOT/nav.adoc     |  1 +
 .../modules/ROOT/pages/codegen.adoc           | 55 +++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 spring-graphql-docs/modules/ROOT/pages/codegen.adoc

diff --git a/spring-graphql-docs/modules/ROOT/nav.adoc b/spring-graphql-docs/modules/ROOT/nav.adoc
index d503f51e..d1007f1b 100644
--- a/spring-graphql-docs/modules/ROOT/nav.adoc
+++ b/spring-graphql-docs/modules/ROOT/nav.adoc
@@ -7,6 +7,7 @@
 * xref:observability.adoc[]
 * xref:graalvm-native.adoc[]
 * xref:client.adoc[]
+* xref:codegen.adoc[]
 * xref:graphiql.adoc[]
 * xref:testing.adoc[]
 * xref:boot-starter.adoc[]
diff --git a/spring-graphql-docs/modules/ROOT/pages/codegen.adoc b/spring-graphql-docs/modules/ROOT/pages/codegen.adoc
new file mode 100644
index 00000000..fe4457b8
--- /dev/null
+++ b/spring-graphql-docs/modules/ROOT/pages/codegen.adoc
@@ -0,0 +1,55 @@
+[[codegen]]
+= Code Generation
+
+You can use tools such as
+https://netflix.github.io/dgs/generating-code-from-schema/[DGS Code Generation] to generate
+Java types from the GraphQL schema. The following can be generated:
+
+1. Client types for requests (e.g. queries, mutations) input types, and other types to
+express the response selection set.
+2. Data types.
+3. Server handling classes (e.g. controllers).
+
+Code generation provides convenience initially, but is not ideal for your own application
+domain types over which you'll typically want control. For client types, however, code
+generation can be very useful since you typically don't need to manually change generated
+request types, input types, and selection set types. Response types could be imported,
+if you have access to them, or otherwise could also be generated.
+
+Client generated types can be used with Spring's `GraphQlClient`. Start by following the
+instructions for the DGS code generation plugin to generate client API types. Then, given
+a schema like this:
+
+[source,graphql,indent=0,subs="verbatim,quotes"]
+----
+    type Query {
+        books: [Book]
+    }
+
+    type Book {
+        id: ID
+        name: String
+    }
+----
+
+DGS Codegen will generate a `BooksGraphQLQuery` and `BooksProjectionRoot` classes.
+You can then use those with Spring's `GraphQlClient` along with your own `Book` class
+for the response:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+    HttpGraphQlClient client =
+            HttpGraphQlClient.create(WebClient.create("http://localhost:8080/graphql"));
+
+    BooksGraphQLQuery query = new BooksGraphQLQuery();
+    String document = new GraphQLQueryRequest(query, new BooksProjectionRoot<>().id().name()).serialize();
+
+    List<Book> books = client.document(document)
+            .retrieve(query.getOperationName())
+            .toEntityList(Book.class)
+            .block();
+----
+
+NOTE: Spring Initializer at https://start.spring.io is scheduled to add support for the DGS
+Code Generation with Gradle and Maven. See
+https://github.com/spring-io/start.spring.io/pull/1348[start.spring.io#1348].
\ No newline at end of file