@@ -394,6 +394,48 @@ however, that such a visitor cannot change the schema. See
394
394
<<execution.graphqlsource.schema-transformation>>, if you need to make changes to the schema.
395
395
396
396
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
+
397
439
[[execution.graphqlsource.operation-caching]]
398
440
==== Operation Caching
399
441
0 commit comments