Skip to content

Commit 558c9a9

Browse files
committed
add description to schema itself and test it
1 parent 497d2ac commit 558c9a9

8 files changed

Lines changed: 100 additions & 9 deletions

File tree

‎src/main/antlr/GraphqlSDL.g4‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
grammar GraphqlSDL;
22
import GraphqlCommon;
33

4-
typeSystemDefinition: description?
4+
typeSystemDefinition:
55
schemaDefinition |
66
typeDefinition |
77
directiveDefinition

‎src/main/java/graphql/introspection/Introspection.java‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -474,6 +474,9 @@ public enum DirectiveLocation {
474474
.description("A GraphQL Introspection defines the capabilities" +
475475
" of a GraphQL server. It exposes all available types and directives on " +
476476
"the server, the entry points for query, mutation, and subscription operations.")
477+
.field(newFieldDefinition()
478+
.name("description")
479+
.type(GraphQLString))
477480
.field(newFieldDefinition()
478481
.name("types")
479482
.description("A list of all types supported by this server.")
@@ -497,6 +500,9 @@ public enum DirectiveLocation {
497500
.build();
498501

499502
static {
503+
register(__Schema, "description", environment -> {
504+
return environment.getGraphQLSchema().getDescription();
505+
});
500506
register(__Schema, "types", environment -> {
501507
GraphQLSchema schema = environment.getSource();
502508
return schema.getAllTypesAsList();
@@ -564,6 +570,7 @@ public enum DirectiveLocation {
564570
* @param schema the schema to use
565571
* @param parentType the type of the parent object
566572
* @param fieldName the field to look up
573+
*
567574
* @return a field definition otherwise throws an assertion exception if its null
568575
*/
569576
public static GraphQLFieldDefinition getFieldDef(GraphQLSchema schema, GraphQLCompositeType parentType, String fieldName) {

‎src/main/java/graphql/language/SchemaDefinition.java‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,22 +17,24 @@
1717
import static graphql.language.NodeUtil.directivesByName;
1818

1919
@PublicApi
20-
public class SchemaDefinition extends AbstractNode<SchemaDefinition> implements SDLDefinition<SchemaDefinition> {
20+
public class SchemaDefinition extends AbstractDescribedNode<SchemaDefinition> implements SDLDefinition<SchemaDefinition> {
2121

2222
private final List<Directive> directives;
2323
private final List<OperationTypeDefinition> operationTypeDefinitions;
2424

2525
public static final String CHILD_DIRECTIVES = "directives";
2626
public static final String CHILD_OPERATION_TYPE_DEFINITIONS = "operationTypeDefinitions";
2727

28+
2829
@Internal
2930
protected SchemaDefinition(List<Directive> directives,
3031
List<OperationTypeDefinition> operationTypeDefinitions,
3132
SourceLocation sourceLocation,
3233
List<Comment> comments,
3334
IgnoredChars ignoredChars,
34-
Map<String, String> additionalData) {
35-
super(sourceLocation, comments, ignoredChars, additionalData);
35+
Map<String, String> additionalData,
36+
Description description) {
37+
super(sourceLocation, comments, ignoredChars, additionalData, description);
3638
this.directives = directives;
3739
this.operationTypeDefinitions = operationTypeDefinitions;
3840
}
@@ -54,6 +56,10 @@ public List<OperationTypeDefinition> getOperationTypeDefinitions() {
5456
return new ArrayList<>(operationTypeDefinitions);
5557
}
5658

59+
public Description getDescription() {
60+
return description;
61+
}
62+
5763
@Override
5864
public List<Node> getChildren() {
5965
List<Node> result = new ArrayList<>();
@@ -92,7 +98,7 @@ public boolean isEqualTo(Node o) {
9298
@Override
9399
public SchemaDefinition deepCopy() {
94100
return new SchemaDefinition(deepCopy(directives), deepCopy(operationTypeDefinitions), getSourceLocation(), getComments(),
95-
getIgnoredChars(), getAdditionalData());
101+
getIgnoredChars(), getAdditionalData(), description);
96102
}
97103

98104
@Override
@@ -125,6 +131,8 @@ public static final class Builder implements NodeBuilder {
125131
private List<OperationTypeDefinition> operationTypeDefinitions = new ArrayList<>();
126132
private IgnoredChars ignoredChars = IgnoredChars.EMPTY;
127133
private Map<String, String> additionalData = new LinkedHashMap<>();
134+
private Description description;
135+
128136

129137
protected Builder() {
130138
}
@@ -136,8 +144,13 @@ protected Builder(SchemaDefinition existing) {
136144
this.operationTypeDefinitions = existing.getOperationTypeDefinitions();
137145
this.ignoredChars = existing.getIgnoredChars();
138146
this.additionalData = new LinkedHashMap<>(existing.getAdditionalData());
147+
this.description = existing.getDescription();
139148
}
140149

150+
public Builder description(Description description) {
151+
this.description = description;
152+
return this;
153+
}
141154

142155
public Builder sourceLocation(SourceLocation sourceLocation) {
143156
this.sourceLocation = sourceLocation;
@@ -190,7 +203,8 @@ public SchemaDefinition build() {
190203
sourceLocation,
191204
comments,
192205
ignoredChars,
193-
additionalData);
206+
additionalData,
207+
description);
194208
}
195209
}
196210
}

‎src/main/java/graphql/language/SchemaExtensionDefinition.java‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,13 @@
1313
@PublicApi
1414
public class SchemaExtensionDefinition extends SchemaDefinition {
1515

16-
protected SchemaExtensionDefinition(List<Directive> directives, List<OperationTypeDefinition> operationTypeDefinitions, SourceLocation sourceLocation, List<Comment> comments, IgnoredChars ignoredChars, Map<String, String> additionalData) {
17-
super(directives, operationTypeDefinitions, sourceLocation, comments, ignoredChars, additionalData);
16+
protected SchemaExtensionDefinition(List<Directive> directives,
17+
List<OperationTypeDefinition> operationTypeDefinitions,
18+
SourceLocation sourceLocation,
19+
List<Comment> comments,
20+
IgnoredChars ignoredChars,
21+
Map<String, String> additionalData) {
22+
super(directives, operationTypeDefinitions, sourceLocation, comments, ignoredChars, additionalData, null);
1823
}
1924

2025
@Override

‎src/main/java/graphql/parser/GraphqlAntlrToLanguage.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -378,6 +378,7 @@ protected SchemaDefinition createSchemaDefinition(GraphqlParser.SchemaDefinition
378378
SchemaDefinition.Builder def = SchemaDefinition.newSchemaDefinition();
379379
addCommonData(def, ctx);
380380
def.directives(createDirectives(ctx.directives()));
381+
def.description(newDescription(ctx.description()));
381382
def.operationTypeDefinitions(ctx.operationTypeDefinition().stream()
382383
.map(this::createOperationTypeDefinition).collect(toList()));
383384
return def.build();

‎src/main/java/graphql/schema/GraphQLSchema.java‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,11 @@ public class GraphQLSchema {
5454
private final Map<String, GraphQLNamedType> typeMap;
5555
private final Map<String, List<GraphQLObjectType>> byInterface;
5656

57+
private final String description;
58+
5759
/**
5860
* @param queryType the query type
61+
*
5962
* @deprecated use the {@link #newSchema()} builder pattern instead, as this constructor will be made private in a future version.
6063
*/
6164
@Internal
@@ -68,6 +71,7 @@ public GraphQLSchema(GraphQLObjectType queryType) {
6871
* @param queryType the query type
6972
* @param mutationType the mutation type
7073
* @param additionalTypes additional types
74+
*
7175
* @deprecated use the {@link #newSchema()} builder pattern instead, as this constructor will be made private in a future version.
7276
*/
7377
@Internal
@@ -81,6 +85,7 @@ public GraphQLSchema(GraphQLObjectType queryType, GraphQLObjectType mutationType
8185
* @param mutationType the mutation type
8286
* @param subscriptionType the subscription type
8387
* @param additionalTypes additional types
88+
*
8489
* @deprecated use the {@link #newSchema()} builder pattern instead, as this constructor will be made private in a future version.
8590
*/
8691
@Internal
@@ -110,6 +115,7 @@ private GraphQLSchema(Builder builder, boolean afterTransform) {
110115
SchemaUtil schemaUtil = new SchemaUtil();
111116
this.typeMap = new TreeMap<>(schemaUtil.allTypes(this, additionalTypes, afterTransform));
112117
this.byInterface = new TreeMap<>(schemaUtil.groupImplementations(this));
118+
this.description = builder.description;
113119
}
114120

115121
// This can be removed once we no longer extract legacy code from types such as data fetchers but for now
@@ -128,6 +134,7 @@ private GraphQLSchema(GraphQLSchema otherSchema, GraphQLCodeRegistry codeRegistr
128134

129135
this.typeMap = otherSchema.typeMap;
130136
this.byInterface = otherSchema.byInterface;
137+
this.description = otherSchema.description;
131138
}
132139

133140

@@ -147,7 +154,9 @@ public GraphQLType getType(String typeName) {
147154
* Called to return a named {@link graphql.schema.GraphQLObjectType} from the schema
148155
*
149156
* @param typeName the name of the type
157+
*
150158
* @return a graphql object type or null if there is one
159+
*
151160
* @throws graphql.GraphQLException if the type is NOT a object type
152161
*/
153162
public GraphQLObjectType getObjectType(String typeName) {
@@ -172,6 +181,7 @@ public List<GraphQLNamedType> getAllTypesAsList() {
172181
* interface type.
173182
*
174183
* @param type interface type to obtain implementations of.
184+
*
175185
* @return list of types implementing provided interface
176186
*/
177187
public List<GraphQLObjectType> getImplementations(GraphQLInterfaceType type) {
@@ -189,6 +199,7 @@ public List<GraphQLObjectType> getImplementations(GraphQLInterfaceType type) {
189199
*
190200
* @param abstractType abstract type either interface or union
191201
* @param concreteType concrete type
202+
*
192203
* @return true if possible type, false otherwise.
193204
*/
194205
public boolean isPossibleType(GraphQLNamedType abstractType, GraphQLObjectType concreteType) {
@@ -219,6 +230,7 @@ public GraphQLObjectType getSubscriptionType() {
219230

220231
/**
221232
* @return the field visibility
233+
*
222234
* @deprecated use {@link GraphQLCodeRegistry#getFieldVisibility()} instead
223235
*/
224236
@Deprecated
@@ -307,11 +319,16 @@ public boolean isSupportingSubscriptions() {
307319
return subscriptionType != null;
308320
}
309321

322+
public String getDescription() {
323+
return description;
324+
}
325+
310326
/**
311327
* This helps you transform the current GraphQLSchema object into another one by starting a builder with all
312328
* the current values and allows you to transform it how you want.
313329
*
314330
* @param builderConsumer the consumer code that will be given a builder to transform
331+
*
315332
* @return a new GraphQLSchema object based on calling build on that builder
316333
*/
317334
public GraphQLSchema transform(Consumer<Builder> builderConsumer) {
@@ -332,6 +349,7 @@ public static Builder newSchema() {
332349
* schema and then allows you to replace them.
333350
*
334351
* @param existingSchema the existing schema
352+
*
335353
* @return a new schema builder
336354
*/
337355
public static Builder newSchema(GraphQLSchema existingSchema) {
@@ -345,7 +363,8 @@ public static Builder newSchema(GraphQLSchema existingSchema) {
345363
.additionalDirectives(existingSchema.directives)
346364
.clearSchemaDirectives()
347365
.withSchemaDirectives(schemaDirectivesArray(existingSchema))
348-
.additionalTypes(existingSchema.additionalTypes);
366+
.additionalTypes(existingSchema.additionalTypes)
367+
.description(existingSchema.getDescription());
349368
}
350369

351370
private static GraphQLDirective[] schemaDirectivesArray(GraphQLSchema existingSchema) {
@@ -361,6 +380,7 @@ public static class Builder {
361380
private Set<GraphQLType> additionalTypes = new LinkedHashSet<>();
362381
private SchemaDefinition definition;
363382
private List<SchemaExtensionDefinition> extensionDefinitions;
383+
private String description;
364384

365385
// we default these in
366386
private Set<GraphQLDirective> additionalDirectives = new LinkedHashSet<>(
@@ -399,7 +419,9 @@ public Builder subscription(GraphQLObjectType subscriptionType) {
399419

400420
/**
401421
* @param fieldVisibility the field visibility
422+
*
402423
* @return this builder
424+
*
403425
* @deprecated use {@link graphql.schema.GraphQLCodeRegistry.Builder#fieldVisibility(graphql.schema.visibility.GraphqlFieldVisibility)} instead
404426
*/
405427
@Deprecated
@@ -481,11 +503,18 @@ public Builder extensionDefinitions(List<SchemaExtensionDefinition> extensionDef
481503
return this;
482504
}
483505

506+
public Builder description(String description) {
507+
this.description = description;
508+
return this;
509+
}
510+
484511
/**
485512
* Builds the schema
486513
*
487514
* @param additionalTypes - please dont use this any more
515+
*
488516
* @return the built schema
517+
*
489518
* @deprecated - Use the {@link #additionalType(GraphQLType)} methods
490519
*/
491520
@Deprecated
@@ -498,7 +527,9 @@ public GraphQLSchema build(Set<GraphQLType> additionalTypes) {
498527
*
499528
* @param additionalTypes - please don't use this any more
500529
* @param additionalDirectives - please don't use this any more
530+
*
501531
* @return the built schema
532+
*
502533
* @deprecated - Use the {@link #additionalType(GraphQLType)} and {@link #additionalDirective(GraphQLDirective)} methods
503534
*/
504535
@Deprecated

‎src/main/java/graphql/schema/idl/SchemaGenerator.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,9 @@ public SchemaGenerator() {
218218
*
219219
* @param typeRegistry this can be obtained via {@link SchemaParser#parse(String)}
220220
* @param wiring this can be built using {@link RuntimeWiring#newRuntimeWiring()}
221+
*
221222
* @return an executable schema
223+
*
222224
* @throws SchemaProblem if there are problems in assembling a schema such as missing type resolvers or no operations defined
223225
*/
224226
public GraphQLSchema makeExecutableSchema(TypeDefinitionRegistry typeRegistry, RuntimeWiring wiring) throws SchemaProblem {
@@ -232,7 +234,9 @@ public GraphQLSchema makeExecutableSchema(TypeDefinitionRegistry typeRegistry, R
232234
* @param options the controlling options
233235
* @param typeRegistry this can be obtained via {@link SchemaParser#parse(String)}
234236
* @param wiring this can be built using {@link RuntimeWiring#newRuntimeWiring()}
237+
*
235238
* @return an executable schema
239+
*
236240
* @throws SchemaProblem if there are problems in assembling a schema such as missing type resolvers or no operations defined
237241
*/
238242
public GraphQLSchema makeExecutableSchema(Options options, TypeDefinitionRegistry typeRegistry, RuntimeWiring wiring) throws SchemaProblem {
@@ -273,6 +277,9 @@ private GraphQLSchema makeExecutableSchemaImpl(BuildContext buildCtx) {
273277
GraphQLCodeRegistry codeRegistry = buildCtx.getCodeRegistry().build();
274278
schemaBuilder.codeRegistry(codeRegistry);
275279

280+
buildCtx.typeRegistry.schemaDefinition().ifPresent(schemaDefinition -> {
281+
schemaBuilder.description(schemaGeneratorHelper.buildDescription(schemaDefinition, schemaDefinition.getDescription()));
282+
});
276283
GraphQLSchema graphQLSchema = schemaBuilder.build();
277284

278285
Collection<SchemaGeneratorPostProcessing> schemaTransformers = buildCtx.getWiring().getSchemaGeneratorPostProcessings();
@@ -356,6 +363,7 @@ private GraphQLObjectType buildOperation(BuildContext buildCtx, OperationTypeDef
356363
* but then we build the rest of the types specified and put them in as additional types
357364
*
358365
* @param buildCtx the context we need to work out what we are doing
366+
*
359367
* @return the additional types not referenced from the top level operations
360368
*/
361369
private Set<GraphQLType> buildAdditionalTypes(BuildContext buildCtx) {
@@ -400,6 +408,7 @@ private Set<GraphQLDirective> buildAdditionalDirectives(BuildContext buildCtx) {
400408
*
401409
* @param buildCtx the context we need to work out what we are doing
402410
* @param rawType the type to be built
411+
*
403412
* @return an output type
404413
*/
405414
@SuppressWarnings({"unchecked", "TypeParameterUnusedInFormals"})

‎src/test/groovy/graphql/introspection/IntrospectionTest.groovy‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,4 +57,28 @@ class IntrospectionTest extends Specification {
5757
]
5858
]
5959
}
60+
61+
def "schema description can be defined in SDL and queried via introspection"() {
62+
given:
63+
def sdl = '''
64+
"""
65+
This is my schema
66+
"""
67+
schema {
68+
query: Foo
69+
}
70+
71+
type Foo {
72+
foo: String
73+
}
74+
75+
'''
76+
def graphql = TestUtil.graphQL(sdl).build()
77+
when:
78+
def data = graphql.execute("{__schema { description }}").getData()
79+
80+
then:
81+
data == [__schema: [description: "This is my schema"]]
82+
83+
}
6084
}

0 commit comments

Comments
 (0)