Skip to content

Commit ca526f5

Browse files
committed
Document schema mapping inspection
Closes gh-662
1 parent 5eb4e1a commit ca526f5

File tree

1 file changed

+42
-0
lines changed

1 file changed

+42
-0
lines changed

spring-graphql-docs/src/docs/asciidoc/index.adoc

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,48 @@ however, that such a visitor cannot change the schema. See
394394
<<execution.graphqlsource.schema-transformation>>, if you need to make changes to the schema.
395395

396396

397+
[[execution.graphqlsource.schema-mapping-inspection]]
398+
==== Schema Mapping Inspection
399+
400+
If a a query, mutation, or subscription operation does not have a `DataFetcher`, it won't
401+
return any data, and won't do anything useful. Fields on schema types returned by
402+
an operation should be covered by an explicit `DataFetcher` registration, or implicitly by
403+
the default `PropertyDataFetcher`, which looks for a matching Java object property, or
404+
otherwise they will always be `null`.
405+
406+
GraphQL Java does not perform checks to ensure every schema field is covered one way or
407+
another, and that means at runtime you'll get either an error for a non-null field, or
408+
a "silent" `null`. As a lower level library, GraphQL Java simply does not know enough
409+
about `DataFetcher` implementations and their return types, and can't effectively compare
410+
schema types against Java objects.
411+
412+
Spring for GraphQL defines the `SelfDescribingDataFetcher` interface to allow a
413+
`DataFetcher` to expose return type information. All Spring `DataFetcher` implementations
414+
including those for <<controllers>>, and for <<data.querydsl>> and <<data.querybyexample>>
415+
implement this interface. For annotated controllers, the return type is
416+
transparently sourced from `@SchemaMapping` method signature.
417+
418+
On startup, Spring for GraphQL checks schema mappings to ensure every field has either an
419+
explicit `DataFetcher`, or a matching Java object property. The inspection is performed
420+
automatically, and results in a report logged at INFO level. For example:
421+
422+
----
423+
GraphQL schema inspection:
424+
Unmapped fields: {Book=[title], Author[firstName, lastName]} // <1>
425+
Skipped types: [BookOrAuthor] // <2>
426+
----
427+
428+
<1> List of schema fields (and source types) that are not mapped
429+
<2> List of schema types that are skipped (explained next)
430+
431+
There are limits to what the inspection can do, mainly when there is insufficient Java
432+
type information. This is the case if an annotated controller method returns
433+
`java.lang.Object` such as for a `union` type, or if a `DataFetcher` does not implement
434+
`SelfDescribingDataFetcher`. If a type is skipped it is included as such in the
435+
report summary. For `interface` types, the inspection checks only interface declared
436+
fields against the properties of the `DataFetcher` declared Java return type.
437+
438+
397439
[[execution.graphqlsource.operation-caching]]
398440
==== Operation Caching
399441

0 commit comments

Comments
 (0)