[docs] update information about optional arguments and default values (ExpediaGroup#1367)

* [docs] update information about optional arguments and default values

* fix ktlint

Author: Dariusz Kuc

generator/graphql-kotlin-schema-generator/src/test/kotlin/com/expediagroup/graphql/generator/execution/FunctionDataFetcherTest.kt

@@ -76,8 +76,15 @@ class FunctionDataFetcherTest {
             is OptionalInput.Undefined -> "input was UNDEFINED"
             is OptionalInput.Defined -> "first input was ${input.value?.first()?.field1}"
         }
+
+        fun optionalWrapperClass(input: InputWrapper) = when (input.optional) {
+            is OptionalInput.Undefined -> "optional was UNDEFINED"
+            is OptionalInput.Defined -> "optional was ${input.optional.value}"
+        }
     }
 
+    data class InputWrapper(val required: String, val optional: OptionalInput<String>)
+
     @GraphQLName("MyInputClassRenamed")
     data class MyInputClass(
         @JsonProperty("jacksonField")
@@ -149,7 +156,7 @@ class FunctionDataFetcherTest {
     }
 
     @Test
-    fun `default values are overriden when arument is passed in`() {
+    fun `default values are overridden when arument is passed in`() {
         val dataFetcher = FunctionDataFetcher(target = null, fn = MyClass::printDefault)
         val mockEnvironment: DataFetchingEnvironment = mockk {
             every { getSource<Any>() } returns MyClass()
@@ -276,6 +283,16 @@ class FunctionDataFetcherTest {
         assertEquals(expected = "input was hello", actual = dataFetcher.get(mockEnvironment))
     }
 
+    @Test
+    fun `optional inputs return the value when null arguments are passed`() {
+        val dataFetcher = FunctionDataFetcher(target = MyClass(), fn = MyClass::optionalWrapper)
+        val mockEnvironment: DataFetchingEnvironment = mockk {
+            every { arguments } returns mapOf("input" to null)
+            every { containsArgument("input") } returns true
+        }
+        assertEquals(expected = "input was null", actual = dataFetcher.get(mockEnvironment))
+    }
+
     @Test
     fun `optional inputs return undefined when arguments are empty`() {
         val dataFetcher = FunctionDataFetcher(target = MyClass(), fn = MyClass::optionalWrapper)
@@ -296,4 +313,24 @@ class FunctionDataFetcherTest {
         val result = dataFetcher.get(mockEnvironment)
         assertEquals(expected = "first input was foo", actual = result)
     }
+
+    @Test
+    fun `optional inputs inside class return the value when arguments are passed`() {
+        val dataFetcher = FunctionDataFetcher(target = MyClass(), fn = MyClass::optionalWrapperClass)
+        val mockEnvironment: DataFetchingEnvironment = mockk {
+            every { arguments } returns mapOf("input" to mapOf("required" to "hello", "optional" to "hello"))
+            every { containsArgument("input") } returns true
+        }
+        assertEquals(expected = "optional was hello", actual = dataFetcher.get(mockEnvironment))
+    }
+
+    @Test
+    fun `optional inputs inside class return undefined when arguments are empty`() {
+        val dataFetcher = FunctionDataFetcher(target = MyClass(), fn = MyClass::optionalWrapperClass)
+        val mockEnvironment: DataFetchingEnvironment = mockk {
+            every { arguments } returns mapOf("input" to mapOf("required" to "hello"))
+            every { containsArgument("input") } returns true
+        }
+        assertEquals(expected = "optional was UNDEFINED", actual = dataFetcher.get(mockEnvironment))
+    }
 }

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

@@ -16,10 +16,11 @@ value and explicit `null` value.
 
 `OptionalInput` is a convenient sealed class wrapper that provides distinction between undefined, null, and non-null
 values. If the argument is not specified in the request it will be represented as a `OptionalInput.Undefined` object, otherwise the
-value will be wrapped in `OptionalInput.Defined` class.
+value will be wrapped in `OptionalInput.Defined` class. As a best practice, we highly recommend to set appropriate
+[default values to all optional arguments](https://opensource.expediagroup.com/graphql-kotlin/docs/schema-generator/writing-schemas/arguments#default-values).
 
 ```kotlin
-fun optionalInput(input: OptionalInput<String>): String = when (input) {
+fun optionalInput(input: OptionalInput<String> = OptionalInput.Undefined): String = when (input) {
     is OptionalInput.Undefined -> "input was not specified"
     is OptionalInput.Defined<String> -> "input value: ${input.value}"
 }