|
1 | | ---- |
2 | | -id: arguments |
3 | | -title: Arguments |
4 | | ---- |
5 | | - |
6 | | -Method arguments are automatically exposed as part of the arguments to the corresponding GraphQL fields. |
7 | | - |
8 | | -```kotlin |
9 | | -class SimpleQuery{ |
10 | | - |
11 | | - @GraphQLDescription("performs some operation") |
12 | | - fun doSomething(@GraphQLDescription("super important value") value: Int): Boolean = true |
13 | | -} |
14 | | -``` |
15 | | - |
16 | | -The above Kotlin code will generate following GraphQL schema: |
17 | | - |
18 | | -```graphql |
19 | | -type Query { |
20 | | - """performs some operation""" |
21 | | - doSomething( |
22 | | - """super important value""" |
23 | | - value: Int! |
24 | | - ): Boolean! |
25 | | -} |
26 | | -``` |
27 | | - |
28 | | -This behavior is true for all arguments except for the GraphQL context objects. See section below for detailed |
29 | | -information about `@GraphQLContext`. |
30 | | - |
31 | | -### Input Types |
32 | | - |
33 | | -Query and mutation function arguments are automatically converted to corresponding GraphQL input fields. GraphQL makes a |
34 | | -distinction between input and output types and requires unique names for all the types. Since we can use the same |
35 | | -objects for input and output in our Kotlin functions, `graphql-kotlin-schema-generator` will automatically append |
36 | | -`Input` suffix to the query input objects. |
37 | | - |
38 | | -```kotlin |
39 | | -class WidgetMutation { |
40 | | - |
41 | | - @GraphQLDescription("modifies passed in widget so it doesn't have null value") |
42 | | - fun processWidget(@GraphQLDescription("widget to be modified") widget: Widget): Widget { |
43 | | - if (null == widget.value) { |
44 | | - widget.value = 42 |
45 | | - } |
46 | | - return widget |
47 | | - } |
48 | | -} |
49 | | - |
50 | | -@GraphQLDescription("A useful widget") |
51 | | -data class Widget( |
52 | | - @GraphQLDescription("The widget's value that can be null") |
53 | | - var value: Int? = nul |
54 | | -) { |
55 | | - @GraphQLDescription("returns original value multiplied by target OR null if original value was null") |
56 | | - fun multiplyValueBy(multiplier: Int) = value?.times(multiplier) |
57 | | -} |
58 | | -``` |
59 | | - |
60 | | -Will generate |
61 | | - |
62 | | -```graphql |
63 | | -type Mutation { |
64 | | - """modifies passed in widget so it doesn't have null value""" |
65 | | - processWidget( |
66 | | - """widget to be modified""" |
67 | | - widget: WidgetInput! |
68 | | - ): Widget! |
69 | | -} |
70 | | - |
71 | | -"""A useful widget""" |
72 | | -type Widget { |
73 | | - |
74 | | - """The widget's value that can be null""" |
75 | | - value: Int |
76 | | - |
77 | | - """ |
78 | | - returns original value multiplied by target OR null if original value was null |
79 | | - """ |
80 | | - multiplyValueBy(multiplier: Int!): Int |
81 | | -} |
82 | | - |
83 | | -"""A useful widget""" |
84 | | -input WidgetInput { |
85 | | - |
86 | | - """The widget's value that can be null""" |
87 | | - value: Int |
88 | | -} |
89 | | - |
90 | | -``` |
91 | | - |
92 | | -Please note that only fields are exposed in the input objects. Functions will only be available on the GraphQL output |
93 | | -types. |
94 | | - |
95 | | -If you know a type will only be used for input types you can call your class `CustomTypeInput`. The library will not |
96 | | -append `Input` if the class name already ends with `Input` but that means you can not use this type as output because |
97 | | -the schema would have two types with the same name and will be invalid. |
98 | | - |
99 | | -### Optional input fields |
100 | | - |
101 | | -Kotlin requires variables/values to be initialized upon their declaration either from the user input OR by providing |
102 | | -defaults (even if they are marked as nullable). Therefore in order for GraphQL input field to be optional it needs to be |
103 | | -nullable and also specify default Kotlin value. |
104 | | - |
105 | | -```kotlin |
106 | | - @GraphQLDescription("query with optional input") |
107 | | - fun doSomethingWithOptionalInput( |
108 | | - @GraphQLDescription("this field is required") requiredValue: Int, |
109 | | - @GraphQLDescription("this field is optional") optionalValue: Int?) |
110 | | - = "required value=$requiredValue, optional value=$optionalValue" |
111 | | -``` |
112 | | - |
113 | | -NOTE: Non nullable input fields will always require users to specify the value regardless whether default Kotlin value |
114 | | -is provided or not. |
115 | | - |
116 | | -NOTE: Even though you could specify a default value in Kotlin `optionalValue: Int? = null`, this will not be used since |
117 | | -if no value is provided to the schema `graphql-java` passes null as the value so the Kotlin default value will never be |
118 | | -used, like in this argument `optionalList: List<Int>? = emptyList()`, the value will be null if not passed a value by |
119 | | -the client. |
120 | | - |
121 | | -### Default values |
122 | | - |
123 | | -Default argument values are currently not supported. See issue |
124 | | -[#53](https://github.com/ExpediaGroup/graphql-kotlin/issues/53) for more details. |
| 1 | +--- |
| 2 | +id: arguments |
| 3 | +title: Arguments |
| 4 | +--- |
| 5 | + |
| 6 | +Method arguments are automatically exposed as part of the arguments to the corresponding GraphQL fields. |
| 7 | + |
| 8 | +```kotlin |
| 9 | +class SimpleQuery{ |
| 10 | + |
| 11 | + @GraphQLDescription("performs some operation") |
| 12 | + fun doSomething(@GraphQLDescription("super important value") value: Int): Boolean = true |
| 13 | +} |
| 14 | +``` |
| 15 | + |
| 16 | +The above Kotlin code will generate following GraphQL schema: |
| 17 | + |
| 18 | +```graphql |
| 19 | +type Query { |
| 20 | + """performs some operation""" |
| 21 | + doSomething( |
| 22 | + """super important value""" |
| 23 | + value: Int! |
| 24 | + ): Boolean! |
| 25 | +} |
| 26 | +``` |
| 27 | + |
| 28 | +This behavior is true for all arguments except for the special classes for the [GraphQLContext](../execution/contextual-data) and the [DataFetchingEnvironment](../execution/data-fetching-environment) |
| 29 | + |
| 30 | +### Input Types |
| 31 | + |
| 32 | +Query and mutation function arguments are automatically converted to corresponding GraphQL input fields. GraphQL makes a |
| 33 | +distinction between input and output types and requires unique names for all the types. Since we can use the same |
| 34 | +objects for input and output in our Kotlin functions, `graphql-kotlin-schema-generator` will automatically append |
| 35 | +an `Input` suffix to the query input objects. |
| 36 | + |
| 37 | +For example, the following code: |
| 38 | + |
| 39 | +```kotlin |
| 40 | +class WidgetMutation { |
| 41 | + |
| 42 | + @GraphQLDescription("modifies passed in widget so it doesn't have null value") |
| 43 | + fun processWidget(@GraphQLDescription("widget to be modified") widget: Widget): Widget { |
| 44 | + if (null == widget.value) { |
| 45 | + widget.value = 42 |
| 46 | + } |
| 47 | + return widget |
| 48 | + } |
| 49 | +} |
| 50 | + |
| 51 | +@GraphQLDescription("A useful widget") |
| 52 | +data class Widget( |
| 53 | + @GraphQLDescription("The widget's value that can be null") |
| 54 | + var value: Int? = nul |
| 55 | +) { |
| 56 | + @GraphQLDescription("returns original value multiplied by target OR null if original value was null") |
| 57 | + fun multiplyValueBy(multiplier: Int) = value?.times(multiplier) |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +Will generate the following schema: |
| 62 | + |
| 63 | +```graphql |
| 64 | +type Mutation { |
| 65 | + """modifies passed in widget so it doesn't have null value""" |
| 66 | + processWidget( |
| 67 | + """widget to be modified""" |
| 68 | + widget: WidgetInput! |
| 69 | + ): Widget! |
| 70 | +} |
| 71 | + |
| 72 | +"""A useful widget""" |
| 73 | +type Widget { |
| 74 | + |
| 75 | + """The widget's value that can be null""" |
| 76 | + value: Int |
| 77 | + |
| 78 | + """ |
| 79 | + returns original value multiplied by target OR null if original value was null |
| 80 | + """ |
| 81 | + multiplyValueBy(multiplier: Int!): Int |
| 82 | +} |
| 83 | + |
| 84 | +"""A useful widget""" |
| 85 | +input WidgetInput { |
| 86 | + |
| 87 | + """The widget's value that can be null""" |
| 88 | + value: Int |
| 89 | +} |
| 90 | + |
| 91 | +``` |
| 92 | + |
| 93 | +Please note that only fields are exposed in the input objects. Functions will only be available on the GraphQL output |
| 94 | +types. |
| 95 | + |
| 96 | +If you know a type will only be used for input types you can call your class something like `CustomTypeInput`. The library will not |
| 97 | +append `Input` if the class name already ends with `Input` but that means you can not use this type as output because |
| 98 | +the schema would have two types with the same name and that would be invalid. |
| 99 | + |
| 100 | +### Optional input fields |
| 101 | + |
| 102 | +Kotlin requires variables/values to be initialized upon their declaration either from the user input OR by providing |
| 103 | +defaults (even if they are marked as nullable). Therefore in order for a GraphQL input field to be optional it needs to be |
| 104 | +nullable and also specify a default Kotlin value. |
| 105 | + |
| 106 | +```kotlin |
| 107 | + @GraphQLDescription("query with optional input") |
| 108 | + fun doSomethingWithOptionalInput( |
| 109 | + @GraphQLDescription("this field is required") requiredValue: Int, |
| 110 | + @GraphQLDescription("this field is optional") optionalValue: Int?) |
| 111 | + = "required value=$requiredValue, optional value=$optionalValue" |
| 112 | +``` |
| 113 | + |
| 114 | +NOTE: Non nullable input fields will always require users to specify the value regardless of whether a default Kotlin value |
| 115 | +is provided or not. |
| 116 | + |
| 117 | +NOTE: Even though you could specify a default value in Kotlin `optionalValue: Int? = null`, this will not be used. This is because |
| 118 | +if no value is provided to the schema, `graphql-java` passes null as the value. The Kotlin default value will never be |
| 119 | +used. For example, with argument `optionalList: List<Int>? = emptyList()`, the value will be null if not passed a value by |
| 120 | +the client. |
| 121 | + |
| 122 | +### Default values |
| 123 | + |
| 124 | +Default argument values are currently not supported. See issue |
| 125 | +[#53](https://github.com/ExpediaGroup/graphql-kotlin/issues/53) for more details. |
0 commit comments