Skip to content

Add SchemaPrinter AST comments support #3287

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dondonz merged 6 commits into from
Aug 22, 2023
Merged

Add SchemaPrinter AST comments support #3287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6f5368d
Added support for optional printing of AST definition comments.
vadimofd Aug 11, 2023
8c6c39a
Added few more test scenarios for scalars and directives.
vadimofd Aug 11, 2023
7e1b017
Fixed a couple of minor review comments.
vadimofd Aug 12, 2023
466b0fd
Temporarily excluded directive and scalar comments from the test unti…
vadimofd Aug 15, 2023
097848a
Merge branch 'master' into schema-printer-comments
dondonz Aug 22, 2023
2fb4e10
Fix bracket from merge conflict resolution
dondonz Aug 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 133 additions & 28 deletions src/main/java/graphql/schema/idl/SchemaPrinter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@
import graphql.PublicApi;
import graphql.execution.ValuesResolver;
import graphql.language.AstPrinter;
import graphql.language.Comment;
import graphql.language.Description;
import graphql.language.DirectiveDefinition;
import graphql.language.Document;
import graphql.language.EnumTypeDefinition;
import graphql.language.EnumValueDefinition;
Expand Down Expand Up @@ -109,6 +111,8 @@ public static class Options {

private final GraphqlTypeComparatorRegistry comparatorRegistry;

private final boolean includeAstDefinitionComments;

private Options(boolean includeIntrospectionTypes,
boolean includeScalars,
boolean includeSchemaDefinition,
Expand All @@ -117,7 +121,8 @@ private Options(boolean includeIntrospectionTypes,
boolean descriptionsAsHashComments,
Predicate<String> includeDirective,
Predicate<GraphQLSchemaElement> includeSchemaElement,
GraphqlTypeComparatorRegistry comparatorRegistry) {
GraphqlTypeComparatorRegistry comparatorRegistry,
boolean includeAstDefinitionComments) {
this.includeIntrospectionTypes = includeIntrospectionTypes;
this.includeScalars = includeScalars;
this.includeSchemaDefinition = includeSchemaDefinition;
Expand All @@ -127,6 +132,7 @@ private Options(boolean includeIntrospectionTypes,
this.descriptionsAsHashComments = descriptionsAsHashComments;
this.comparatorRegistry = comparatorRegistry;
this.includeSchemaElement = includeSchemaElement;
this.includeAstDefinitionComments = includeAstDefinitionComments;
}

public boolean isIncludeIntrospectionTypes() {
Expand Down Expand Up @@ -165,6 +171,8 @@ public boolean isUseAstDefinitions() {
return useAstDefinitions;
}

public boolean isIncludeAstDefinitionComments() { return includeAstDefinitionComments; }

public static Options defaultOptions() {
return new Options(false,
true,
Expand All @@ -174,7 +182,8 @@ public static Options defaultOptions() {
false,
directive -> true,
element -> true,
DefaultGraphqlTypeComparatorRegistry.defaultComparators());
DefaultGraphqlTypeComparatorRegistry.defaultComparators(),
false);
}

/**
Expand All @@ -193,7 +202,8 @@ public Options includeIntrospectionTypes(boolean flag) {
this.descriptionsAsHashComments,
this.includeDirective,
this.includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -212,7 +222,8 @@ public Options includeScalarTypes(boolean flag) {
this.descriptionsAsHashComments,
this.includeDirective,
this.includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -234,7 +245,8 @@ public Options includeSchemaDefinition(boolean flag) {
this.descriptionsAsHashComments,
this.includeDirective,
this.includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -258,7 +270,8 @@ public Options includeDirectiveDefinitions(boolean flag) {
this.descriptionsAsHashComments,
this.includeDirective,
this.includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -278,7 +291,8 @@ public Options includeDirectives(boolean flag) {
this.descriptionsAsHashComments,
directive -> flag,
this.includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -297,7 +311,8 @@ public Options includeDirectives(Predicate<String> includeDirective) {
this.descriptionsAsHashComments,
includeDirective,
this.includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -317,7 +332,8 @@ public Options includeSchemaElement(Predicate<GraphQLSchemaElement> includeSchem
this.descriptionsAsHashComments,
this.includeDirective,
includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -337,7 +353,8 @@ public Options useAstDefinitions(boolean flag) {
this.descriptionsAsHashComments,
this.includeDirective,
this.includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -359,7 +376,8 @@ public Options descriptionsAsHashComments(boolean flag) {
flag,
this.includeDirective,
this.includeSchemaElement,
this.comparatorRegistry);
this.comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
Expand All @@ -380,7 +398,30 @@ public Options setComparators(GraphqlTypeComparatorRegistry comparatorRegistry)
this.descriptionsAsHashComments,
this.includeDirective,
this.includeSchemaElement,
comparatorRegistry);
comparatorRegistry,
this.includeAstDefinitionComments);
}

/**
* Sometimes it is useful to allow printing schema comments. This can be achieved by providing comments in the AST definitions.
* <p>
* The default is to ignore these for backward compatibility and due to this being relatively uncommon need.
*
* @param flag whether to include AST definition comments.
*
* @return new instance of Options
*/
public Options includeAstDefinitionComments(boolean flag) {
return new Options(this.includeIntrospectionTypes,
this.includeScalars,
this.includeSchemaDefinition,
this.includeDirectiveDefinitions,
this.useAstDefinitions,
this.descriptionsAsHashComments,
this.includeDirective,
this.includeSchemaElement,
comparatorRegistry,
flag);
}
}

Expand Down Expand Up @@ -741,7 +782,7 @@ private SchemaElementPrinter<GraphQLSchema> schemaPrinter() {
}

if (needsSchemaPrinted) {
if (hasDescription(schema)) {
if (hasAstDefinitionComments(schema) || hasDescription(schema)) {
out.print(printComments(schema, ""));
}
List<GraphQLAppliedDirective> directives = DirectivesUtil.toAppliedDirectives(schema.getSchemaAppliedDirectives(), schema.getSchemaDirectives());
Expand Down Expand Up @@ -777,9 +818,10 @@ String argsString(List<GraphQLArgument> arguments) {
}

String argsString(Class<? extends GraphQLSchemaElement> parent, List<GraphQLArgument> arguments) {
boolean hasAstDefinitionComments = arguments.stream().anyMatch(this::hasAstDefinitionComments);
boolean hasDescriptions = arguments.stream().anyMatch(this::hasDescription);
String halfPrefix = hasDescriptions ? " " : "";
String prefix = hasDescriptions ? " " : "";
String halfPrefix = hasAstDefinitionComments || hasDescriptions ? " " : "";
String prefix = hasAstDefinitionComments || hasDescriptions ? " " : "";
int count = 0;
StringBuilder sb = new StringBuilder();

Expand All @@ -795,11 +837,11 @@ String argsString(Class<? extends GraphQLSchemaElement> parent, List<GraphQLArgu
sb.append("(");
} else {
sb.append(",");
if (!hasDescriptions) {
if (!hasAstDefinitionComments && !hasDescriptions) {
sb.append(" ");
}
}
if (hasDescriptions) {
if (hasAstDefinitionComments || hasDescriptions) {
sb.append("\n");
}
sb.append(printComments(argument, prefix));
Expand All @@ -820,7 +862,7 @@ String argsString(Class<? extends GraphQLSchemaElement> parent, List<GraphQLArgu
count++;
}
if (count > 0) {
if (hasDescriptions) {
if (hasAstDefinitionComments || hasDescriptions) {
sb.append("\n");
}
sb.append(halfPrefix).append(")");
Expand Down Expand Up @@ -1027,18 +1069,26 @@ private String printComments(Object graphQLType, String prefix) {

private void printComments(PrintWriter out, Object graphQLType, String prefix) {
String descriptionText = getDescription(graphQLType);
if (isNullOrEmpty(descriptionText)) {
return;
if (!isNullOrEmpty(descriptionText)) {
List<String> lines = Arrays.asList(descriptionText.split("\n"));
if (options.isDescriptionsAsHashComments()) {
printMultiLineHashDescription(out, prefix, lines);
} else if (!lines.isEmpty()) {
if (lines.size() > 1) {
printMultiLineDescription(out, prefix, lines);
} else {
printSingleLineDescription(out, prefix, lines.get(0));
}
}
}

List<String> lines = Arrays.asList(descriptionText.split("\n"));
if (options.isDescriptionsAsHashComments()) {
printMultiLineHashDescription(out, prefix, lines);
} else if (!lines.isEmpty()) {
if (lines.size() > 1) {
printMultiLineDescription(out, prefix, lines);
} else {
printSingleLineDescription(out, prefix, lines.get(0));
if (options.isIncludeAstDefinitionComments()) {
String commentsText = getAstDefinitionComments(graphQLType);
if (!isNullOrEmpty(commentsText)) {
List<String> lines = Arrays.asList(commentsText.split("\n") );
if (!lines.isEmpty()) {
printMultiLineHashDescription(out, prefix, lines);
}
}
}
}
Expand All @@ -1062,6 +1112,61 @@ private void printSingleLineDescription(PrintWriter out, String prefix, String s
out.printf("%s\"%s\"\n", prefix, desc);
}

private boolean hasAstDefinitionComments(Object commentHolder) {
String comments = getAstDefinitionComments(commentHolder);
return !isNullOrEmpty(comments);
}

private String getAstDefinitionComments(Object commentHolder) {
if (commentHolder instanceof GraphQLObjectType) {
GraphQLObjectType type = (GraphQLObjectType) commentHolder;
return comments(ofNullable(type.getDefinition()).map(ObjectTypeDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLEnumType) {
GraphQLEnumType type = (GraphQLEnumType) commentHolder;
return comments(ofNullable(type.getDefinition()).map(EnumTypeDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLFieldDefinition) {
GraphQLFieldDefinition type = (GraphQLFieldDefinition) commentHolder;
return comments(ofNullable(type.getDefinition()).map(FieldDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLEnumValueDefinition) {
GraphQLEnumValueDefinition type = (GraphQLEnumValueDefinition) commentHolder;
return comments(ofNullable(type.getDefinition()).map(EnumValueDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLUnionType) {
GraphQLUnionType type = (GraphQLUnionType) commentHolder;
return comments(ofNullable(type.getDefinition()).map(UnionTypeDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLInputObjectType) {
GraphQLInputObjectType type = (GraphQLInputObjectType) commentHolder;
return comments(ofNullable(type.getDefinition()).map(InputObjectTypeDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLInputObjectField) {
GraphQLInputObjectField type = (GraphQLInputObjectField) commentHolder;
return comments(ofNullable(type.getDefinition()).map(InputValueDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLInterfaceType) {
GraphQLInterfaceType type = (GraphQLInterfaceType) commentHolder;
return comments(ofNullable(type.getDefinition()).map(InterfaceTypeDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLScalarType) {
GraphQLScalarType type = (GraphQLScalarType) commentHolder;
return comments(ofNullable(type.getDefinition()).map(ScalarTypeDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLArgument) {
GraphQLArgument type = (GraphQLArgument) commentHolder;
return comments(ofNullable(type.getDefinition()).map(InputValueDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLDirective) {
GraphQLDirective type = (GraphQLDirective) commentHolder;
return comments(ofNullable(type.getDefinition()).map(DirectiveDefinition::getComments).orElse(null));
} else if (commentHolder instanceof GraphQLSchema) {
GraphQLSchema type = (GraphQLSchema) commentHolder;
return comments(ofNullable(type.getDefinition()).map(SchemaDefinition::getComments).orElse(null));
} else {
return Assert.assertShouldNeverHappen();
}
}

private String comments(List<Comment> comments) {
if ( comments == null || comments.isEmpty() ) {
return null;
}
String s = comments.stream().map(c -> c.getContent()).collect(joining("\n", "", "\n"));
return s;
}

private boolean hasDescription(Object descriptionHolder) {
String description = getDescription(descriptionHolder);
return !isNullOrEmpty(description);
Expand Down
Loading