[example] Add example of undefined input vs null (#785)

* Add example of undefined input vs null

* Add docs page

* Apply suggestions from code review

Co-authored-by: Dariusz Kuc <[email protected]>

Co-authored-by: Shane Myrick <[email protected]>
Co-authored-by: Dariusz Kuc <[email protected]>

Author: 3 people

docs/schema-generator/execution/optional-undefined-arguments.md

@@ -0,0 +1,37 @@
+---
+id: optional-undefined-arguments
+title: Optional Undefined Arguments
+---
+
+In GraphQL, input types can be optional which means that the client can either:
+
+* Not specify a value at all
+* Send null explictly
+* Send the non-null type
+
+Optional input types are represented as nullable parameters in Kotlin
+```kotlin
+fun optionalInput(value: String?): String? = value
+```
+
+```graphql
+query OptionalInputQuery {
+  undefined: optionalInput
+  null: optionalInput(value: null)
+  foo: optionalInput(value: "foo")
+}
+```
+
+By default, if an optional input value is not specified, then the execution engine will set the argument in Kotlin to `null`.
+This means that you can not tell, by just the value alone, whether the request did not contain any argument or the client explicitly passed in `null`.
+
+Instead, you should inspect the [DataFetchingEnvironment](./data-fetching-environment.md) where you can see if the request had the variable defined and even check parent arguments as well.
+
+```kotlin
+fun optionalInput(value: String?, dataFetchingEnvironment: DataFetchingEnvironment): String =
+    if (dataFetchingEnvironment.containsArgument("value")) {
+        "The value was $value"
+    } else {
+        "The value was undefined"
+    }
+```

examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/mutation/OptionalInputMutation.kt

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2020 Expedia, Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.expediagroup.graphql.examples.mutation
+
+import com.expediagroup.graphql.spring.operations.Mutation
+import graphql.schema.DataFetchingEnvironment
+import org.springframework.stereotype.Component
+
+@Component
+class OptionalInputMutation : Mutation {
+
+    /**
+     * Example of how to check the difference between a client not sending a value
+     * or explicitly passing in null
+     */
+    fun optionalInput(value: String?, dataFetchingEnvironment: DataFetchingEnvironment): String =
+        if (dataFetchingEnvironment.containsArgument("value")) {
+            "The value was $value"
+        } else {
+            "The value was undefined"
+        }
+}

website/sidebars.json

@@ -44,6 +44,7 @@
           "schema-generator/execution/exceptions",
           "schema-generator/execution/data-fetching-environment",
           "schema-generator/execution/contextual-data",
+          "schema-generator/execution/optional-undefined-arguments",
           "schema-generator/execution/subscriptions",
           "schema-generator/execution/introspection"
         ]