Issue #164: descriptions of GraphQL items is now in the generated code

Author: etienne-sf

CHANGELOG.md

@@ -12,9 +12,9 @@ Whether the application uses the _graphql_, the _generateClientCode_ or the _gen
 
 # Not released yet
 
-
 Both modes:
-* Issue #166 : Corrected an issue that prevents to request data when GraphQL field's name are java reserved keywords
+* Issue #166: Corrected an issue that prevents to request data when GraphQL field's name are java reserved keywords
+* Issue #164: the descriptions from the GraphQL schema is now included in the java comments for objects, fields, union...
 
 
 # 1.18.8

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/DocumentParser.java

@@ -25,6 +25,7 @@
 import com.graphql_java_generator.plugin.conf.GraphQLConfiguration;
 import com.graphql_java_generator.plugin.generate_schema.GenerateGraphQLSchemaDocumentParser;
 import com.graphql_java_generator.plugin.language.AppliedDirective;
+import com.graphql_java_generator.plugin.language.Description;
 import com.graphql_java_generator.plugin.language.Directive;
 import com.graphql_java_generator.plugin.language.DirectiveLocation;
 import com.graphql_java_generator.plugin.language.EnumValue;
@@ -482,9 +483,14 @@ public Directive readDirectiveDefinition(DirectiveDefinition node) {
 		directive.setArguments(node.getInputValueDefinitions().stream().map(this::readFieldTypeDefinition)
 				.collect(Collectors.toList()));
 
-		// Let's store its comments
+		// Let's store its comments,
 		directive.setComments(node.getComments());
 
+		// its description,
+		if (node.getDescription() != null) {
+			directive.setDescription(getDescription(node.getDescription()));
+		}
+
 		// and all its locations
 		for (graphql.language.DirectiveLocation dl : node.getDirectiveLocations()) {
 			DirectiveLocation dirLoc = DirectiveLocation.valueOf(DirectiveLocation.class, dl.getName());
@@ -676,6 +682,11 @@ private ObjectType addObjectTypeDefinition(final ObjectType objectType, ObjectTy
 		objectType.getComments()
 				.addAll(node.getComments().stream().map(c -> c.getContent()).collect(Collectors.toList()));
 
+		// and its description,
+		if (node.getDescription() != null) {
+			objectType.setDescription(getDescription(node.getDescription()));
+		}
+
 		// Let's read all the interfaces this object implements
 		for (graphql.language.Type type : node.getImplements()) {
 			if (type instanceof TypeName) {
@@ -710,6 +721,11 @@ ObjectType readInputType(ObjectType objectType, InputObjectTypeDefinition node)
 		objectType.getComments()
 				.addAll(node.getComments().stream().map(c -> c.getContent()).collect(Collectors.toList()));
 
+		// and its description,
+		if (node.getDescription() != null) {
+			objectType.setDescription(getDescription(node.getDescription()));
+		}
+
 		// Let's read all its fields
 		for (InputValueDefinition def : node.getInputValueDefinitions()) {
 			FieldImpl field = readFieldTypeDefinition(def);
@@ -742,6 +758,11 @@ InterfaceType readInterfaceType(InterfaceTypeDefinition node) {
 		// Let's store its comments
 		interfaceType.setComments(node.getComments());
 
+		// and its description,
+		if (node.getDescription() != null) {
+			interfaceType.setDescription(getDescription(node.getDescription()));
+		}
+
 		// Let's read all its fields
 		interfaceType.setFields(node.getFieldDefinitions().stream().map(def -> readField(def, interfaceType))
 				.collect(Collectors.toList()));
@@ -773,6 +794,11 @@ UnionType readUnionType(UnionType unionType, UnionTypeDefinition node) {
 		unionType.getComments()
 				.addAll(node.getComments().stream().map(c -> c.getContent()).collect(Collectors.toList()));
 
+		// and its description,
+		if (node.getDescription() != null) {
+			unionType.setDescription(getDescription(node.getDescription()));
+		}
+
 		for (graphql.language.Type<?> memberType : node.getMemberTypes()) {
 			String memberTypeName = (String) graphqlUtils.invokeMethod("getName", memberType);
 
@@ -834,6 +860,11 @@ CustomScalarType readCustomScalarType(ScalarTypeDefinition node) {
 		// Let's store its comments
 		customScalarType.setComments(node.getComments());
 
+		// and its description,
+		if (node.getDescription() != null) {
+			customScalarType.setDescription(getDescription(node.getDescription()));
+		}
+
 		return customScalarType;
 	}
 
@@ -853,6 +884,11 @@ public EnumType readEnumType(EnumType enumType, EnumTypeDefinition node) {
 		enumType.getComments()
 				.addAll(node.getComments().stream().map(c -> c.getContent()).collect(Collectors.toList()));
 
+		// and its description,
+		if (node.getDescription() != null) {
+			enumType.setDescription(getDescription(node.getDescription()));
+		}
+
 		for (EnumValueDefinition enumValDef : node.getEnumValueDefinitions()) {
 			EnumValue val = EnumValueImpl.builder().name(enumValDef.getName())
 					.appliedDirectives(readAppliedDirectives(enumValDef.getDirectives())).build();
@@ -883,6 +919,11 @@ Field readField(FieldDefinition fieldDef, Type owningType) {
 		// Let's store its comments
 		field.setComments(fieldDef.getComments());
 
+		// and its description
+		if (fieldDef.getDescription() != null) {
+			field.setDescription(getDescription(fieldDef.getDescription()));
+		}
+
 		return field;
 	}
 
@@ -1043,4 +1084,14 @@ protected String getUtilPackageName() {
 		return ((GenerateCodeCommonConfiguration) configuration).getPackageName();
 	}
 
+	/**
+	 * Returns an instance of {@link Description} based on the given String, or null of this string is null
+	 * 
+	 * @param description
+	 * @return
+	 */
+	private Description getDescription(graphql.language.Description description) {
+		return (description == null) ? null : new Description(description);
+	}
+
 }

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/language/DataFetcher.java

@@ -69,7 +69,7 @@ default public String getJavaName() {
 	public DataFetchersDelegate getDataFetcherDelegate();
 
 	/**
-	 * Retrieves the origin of this {@link DataFetcher}, that is: the name of the object which contains the field to
+	 * Retrieves the origin of this {@link DataFetcher}, that is: the name of the object which contains the fields to
 	 * fetch.<BR/>
 	 * There are two kinds of {@link DataFetcher}:
 	 * <UL>

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/language/Description.java

@@ -0,0 +1,65 @@
+/**
+ * 
+ */
+package com.graphql_java_generator.plugin.language;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.StringReader;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * This class matches the description of a GraphQL item, as described in the GraphQL schema. It allows several
+ * capabilities for use in the template, for code or schema generation
+ * 
+ * @author etienne-sf
+ */
+public class Description {
+
+	/** The description as it has been read from the source GraphQL schema */
+	final graphql.language.Description description;
+
+	/** The decomposition of the description in lines, without the EOL character(s) */
+	List<String> lines = null;
+
+	public Description(graphql.language.Description description2) {
+		this.description = description2;
+	}
+
+	/**
+	 * Returns the content of the description
+	 * 
+	 * @return
+	 */
+	public String getContent() {
+		return description.getContent();
+	}
+
+	public boolean isMultiLine() {
+		return description.isMultiLine();
+	}
+
+	/**
+	 * Returns an array of the lines of this description. This array contains at least one item.
+	 * 
+	 * @return
+	 */
+	public List<String> getLines() {
+		if (lines == null) {
+			if (description.isMultiLine()) {
+				try (BufferedReader sr = new BufferedReader(new StringReader(description.getContent()))) {
+					lines = sr.lines().collect(Collectors.toList());
+				} catch (IOException e) {
+					throw new RuntimeException(e.getMessage(), e);
+				}
+			} else {
+				lines = new ArrayList<String>(1);
+				lines.add(description.getContent());
+			}
+		}
+		return lines;
+	}
+
+}

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/language/Directive.java

@@ -18,9 +18,12 @@ public interface Directive {
 	/** A directive may have arguments. An argument is actually a field. */
 	public List<Field> getArguments();
 
-	/** Returns the comments that have been found for this object, in the provided GraphQL schema */
+	/** Returns the comments that have been found before this object, in the provided GraphQL schema */
 	public List<String> getComments();
 
+	/** Returns the description for this object, in the provided GraphQL schema */
+	public Description getDescription();
+
 	/** Returns the list of location that this directive may have */
 	public List<DirectiveLocation> getDirectiveLocations();
 

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/language/Field.java

@@ -201,9 +201,12 @@ default public Set<String> getFieldJavaFullClassnamesFromImplementedInterface()
 	 */
 	public String getAnnotation();
 
-	/** Returns the comments that have been found for this object, in the provided GraphQL schema */
+	/** Returns the comments that have been found before this object, in the provided GraphQL schema */
 	public List<String> getComments();
 
+	/** Returns the description for this object, in the provided GraphQL schema */
+	public Description getDescription();
+
 	/**
 	 * Convert the given name, which is supposed to be in camel case (for instance: thisIsCamelCase) to a pascal case
 	 * string (for instance: ThisIsCamelCase).

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/language/Type.java

@@ -129,9 +129,12 @@ default public String getTargetFileName(String fileType) {
 	 */
 	public void addAnnotation(String annotationToAdd, boolean replace);
 
-	/** Returns the comments that have been found for this object, in the provided GraphQL schema */
+	/** Returns the comments that have been found before this object, in the provided GraphQL schema */
 	public List<String> getComments();
 
+	/** Returns the description for this object, in the provided GraphQL schema */
+	public Description getDescription();
+
 	/**
 	 * The GraphQlType for this type
 	 * 

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/language/impl/AbstractType.java

@@ -12,6 +12,7 @@
 import com.graphql_java_generator.plugin.conf.CommonConfiguration;
 import com.graphql_java_generator.plugin.conf.GraphQLConfiguration;
 import com.graphql_java_generator.plugin.language.AppliedDirective;
+import com.graphql_java_generator.plugin.language.Description;
 import com.graphql_java_generator.plugin.language.Field;
 import com.graphql_java_generator.plugin.language.Type;
 import com.graphql_java_generator.util.GraphqlUtils;
@@ -53,9 +54,12 @@ public abstract class AbstractType implements Type {
 	/** All directives that have been defined in the GraphQL schema for this type */
 	private List<AppliedDirective> appliedDirectives = new ArrayList<>();
 
-	/** The comments that have been found for this object, in the provided GraphQL schema */
+	/** The comments that have been found before this type, in the provided GraphQL schema */
 	private List<String> comments = new ArrayList<>();
 
+	/** The description of this type, in the provided GraphQL schema */
+	private Description description = null;
+
 	/** The GraphQL type for this type */
 	final private GraphQlType graphQlType;
 
@@ -89,18 +93,19 @@ public String getClassSimpleName() {
 		return getJavaName();
 	}
 
-    @Override
-    public String getJavaName() {
-        // Optionally add a prefix and/or suffix to the name
-		String name = Stream.of(getPrefix(), getName(), getSuffix())
-				.filter(Objects::nonNull).collect(Collectors.joining());
+	@Override
+	public String getJavaName() {
+		// Optionally add a prefix and/or suffix to the name
+		String name = Stream.of(getPrefix(), getName(), getSuffix()).filter(Objects::nonNull)
+				.collect(Collectors.joining());
 
 		return GraphqlUtils.graphqlUtils.getJavaName(name);
-    }
+	}
 
 	protected String getPrefix() {
 		return "";
 	}
+
 	protected String getSuffix() {
 		return "";
 	}

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/language/impl/DirectiveImpl.java

@@ -6,6 +6,7 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import com.graphql_java_generator.plugin.language.Description;
 import com.graphql_java_generator.plugin.language.Directive;
 import com.graphql_java_generator.plugin.language.DirectiveLocation;
 import com.graphql_java_generator.plugin.language.Field;
@@ -29,9 +30,12 @@ public class DirectiveImpl implements Directive {
 	/** Returns the list of location that this directive may have */
 	private List<DirectiveLocation> directiveLocations = new ArrayList<>();
 
-	/** The comments that have been found for this object, in the provided GraphQL schema */
+	/** The comments that have been found before this object, in the provided GraphQL schema */
 	private List<String> comments = new ArrayList<>();
 
+	/** The description of this directive, in the provided GraphQL schema */
+	private Description description = null;
+
 	/**
 	 * True if this directive is a standard GraphQL directive, or if it has been defined in the GraphQL schema. Default
 	 * value is false (non standard)

graphql-maven-plugin-logic/src/main/java/com/graphql_java_generator/plugin/language/impl/FieldImpl.java

@@ -9,6 +9,7 @@
 import com.graphql_java_generator.plugin.DocumentParser;
 import com.graphql_java_generator.plugin.generate_code.GenerateCodeDocumentParser;
 import com.graphql_java_generator.plugin.language.AppliedDirective;
+import com.graphql_java_generator.plugin.language.Description;
 import com.graphql_java_generator.plugin.language.Field;
 import com.graphql_java_generator.plugin.language.FieldTypeAST;
 import com.graphql_java_generator.plugin.language.Relation;
@@ -84,10 +85,13 @@ public class FieldImpl implements Field {
 	@Builder.Default
 	private List<AppliedDirective> appliedDirectives = new ArrayList<>();
 
-	/** The comments that have been found for this field, in the provided GraphQL schema */
+	/** The comments that have been found before this field, in the provided GraphQL schema */
 	@Builder.Default
 	private List<String> comments = new ArrayList<>();
 
+	/** The description of this field, in the provided GraphQL schema */
+	private Description description;
+
 	@Override
 	public Type getType() {
 		return documentParser.getType(getGraphQLTypeSimpleName());