You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: book/src/types/input_objects.md
+79-9Lines changed: 79 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ In [Juniper], defining a [GraphQL input object][0] is quite straightforward and
14
14
#[derive(GraphQLInputObject)]
15
15
structCoordinate {
16
16
latitude:f64,
17
-
longitude:f64
17
+
longitude:f64,
18
18
}
19
19
20
20
structRoot;
@@ -32,27 +32,48 @@ impl Root {
32
32
# fnmain() {}
33
33
```
34
34
35
+
[`@oneOf`][input objects][0] could be defined by using the [`#[derive(GraphQLInputObject)]` attribute][2] on a [Rust enum][enum]:
36
+
```rust
37
+
# #![expect(unused_variables, reason ="example")]
38
+
# externcrate juniper;
39
+
# usejuniper::{GraphQLInputObject, ID};
40
+
#
41
+
#[derive(GraphQLInputObject)]
42
+
enumUserBy {
43
+
Id(ID), // Every `enum` variant declares a `Null`able input object field,
44
+
Name(String), // so there is no need to use `Option<String>` explicitly.
45
+
}
46
+
#
47
+
# fnmain() {}
48
+
```
49
+
35
50
36
51
### Renaming
37
52
38
-
Just as with [defining GraphQL objects](objects/index.md#renaming), by default [struct] fields are converted from [Rust]'s standard`snake_case` naming convention into [GraphQL]'s `camelCase` convention:
53
+
Just as with [defining GraphQL objects](objects/index.md#renaming), by default [struct] fields (or [enum] variants) are converted from [Rust]'s standard naming convention into [GraphQL]'s `camelCase` convention:
39
54
```rust
40
55
# externcrate juniper;
41
-
# usejuniper::GraphQLInputObject;
56
+
# usejuniper::{GraphQLInputObject, ID};
42
57
#
43
58
#[derive(GraphQLInputObject)]
44
59
structPerson {
45
60
first_name:String, // exposed as `firstName` in GraphQL schema
46
61
last_name:String, // exposed as `lastName` in GraphQL schema
47
62
}
63
+
64
+
#[derive(GraphQLInputObject)]
65
+
enumUserBy {
66
+
Id(ID), // exposed as `id` in GraphQL schema
67
+
Name(String), // exposed as `name` in GraphQL schema
68
+
}
48
69
#
49
70
# fnmain() {}
50
71
```
51
72
52
73
We can override the name by using the `#[graphql(name = "...")]` attribute:
53
74
```rust
54
75
# externcrate juniper;
55
-
# usejuniper::GraphQLInputObject;
76
+
# usejuniper::{GraphQLInputObject, ID};
56
77
#
57
78
#[derive(GraphQLInputObject)]
58
79
#[graphql(name ="WebPerson")] // now exposed as `WebPerson` in GraphQL schema
@@ -62,14 +83,22 @@ struct Person {
62
83
#[graphql(name ="websiteURL")]
63
84
website_url:Option<String>, // now exposed as `websiteURL` in GraphQL schema
64
85
}
86
+
87
+
#[derive(GraphQLInputObject)]
88
+
#[graphql(name ="By")] // now exposed as `By` in GraphQL schema
89
+
enumUserBy {
90
+
#[graphql(name ="ID")]
91
+
Id(ID), // now exposed as `ID` in GraphQL schema
92
+
Name(String),
93
+
}
65
94
#
66
95
# fnmain() {}
67
96
```
68
97
69
98
Or provide a different renaming policy for all the [struct] fields:
70
99
```rust
71
100
# externcrate juniper;
72
-
# usejuniper::GraphQLInputObject;
101
+
# usejuniper::{GraphQLInputObject, ID};
73
102
#
74
103
#[derive(GraphQLInputObject)]
75
104
#[graphql(rename_all ="none")] // disables any renaming
@@ -78,18 +107,25 @@ struct Person {
78
107
age:i32,
79
108
website_url:Option<String>, // exposed as `website_url` in GraphQL schema
80
109
}
110
+
111
+
#[derive(GraphQLInputObject)]
112
+
#[graphql(rename_all ="none")] // disables any renaming
113
+
enumUserBy {
114
+
Id(ID), // exposed as `Id` in GraphQL schema
115
+
Name(String), // exposed as `Name` in GraphQL schema
116
+
}
81
117
#
82
118
# fnmain() {}
83
119
```
84
-
> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `camelCase` and `none` (disables any renaming).
120
+
> **TIP**: Supported policies are: `SCREAMING_SNAKE_CASE`, `snake_case`, `camelCase` and `none` (disables any renaming).
85
121
86
122
87
123
### Documentation and deprecation
88
124
89
125
Similarly, [GraphQL input fields][1] may also be [documented][7] and [deprecated][9] via `#[graphql(description = "...")]` and `#[graphql(deprecated = "...")]`/[`#[deprecated]`][13] attributes:
90
126
```rust
91
127
# externcrate juniper;
92
-
# usejuniper::GraphQLInputObject;
128
+
# usejuniper::{GraphQLInputObject, ID};
93
129
#
94
130
/// This doc comment is visible only in Rust API docs.
95
131
#[derive(GraphQLInputObject)]
@@ -112,6 +148,28 @@ struct Person {
112
148
#[deprecated]
113
149
another:Option<f64>, // has no description in GraphQL schema
114
150
}
151
+
152
+
/// This doc comment is visible only in Rust API docs.
153
+
#[derive(GraphQLInputObject)]
154
+
#[graphql(description ="This description is visible only in GraphQL schema.")]
155
+
enumUserBy {
156
+
/// This doc comment is visible only in Rust API docs.
157
+
#[graphql(desc ="This description is visible only in GraphQL schema.")]
158
+
// ^^^^ shortcut for a `description` argument
159
+
Id(ID),
160
+
161
+
/// This doc comment is visible in both Rust API docs and GraphQL schema
162
+
/// descriptions.
163
+
// `enum` variants represent `Null`able input fields already, so can be naturally
164
+
// deprecated without any default values.
165
+
#[graphql(deprecated ="Just because.")]
166
+
Name(String),
167
+
168
+
// If no explicit deprecation reason is provided,
169
+
// then the default "No longer supported" one is used.
170
+
#[deprecated]
171
+
Bio(String), // has no description in GraphQL schema
172
+
}
115
173
#
116
174
# fnmain() {}
117
175
```
@@ -120,11 +178,11 @@ struct Person {
120
178
121
179
### Ignoring
122
180
123
-
By default, all [struct] fields are included into the generated [GraphQL input object][0] type. To prevent inclusion of a specific field annotate it with the `#[graphql(ignore)]` attribute:
181
+
By default, all [struct] fields (or [enum] variants) are included into the generated [GraphQL input object][0] type. To prevent inclusion of a specific field/variant annotate it with the `#[graphql(ignore)]` attribute:
124
182
> **WARNING**: Ignored fields must either implement `Default` or be annotated with the `#[graphql(default = <expression>)]` argument.
125
183
```rust
126
184
# externcrate juniper;
127
-
# usejuniper::GraphQLInputObject;
185
+
# usejuniper::{GraphQLInputObject, ID};
128
186
#
129
187
enumSystem {
130
188
Cartesian,
@@ -146,6 +204,15 @@ struct Point2D {
146
204
// ^^^^ alternative naming, up to your preference
147
205
shift:f64,
148
206
}
207
+
208
+
#[derive(GraphQLInputObject)]
209
+
enumUserBy {
210
+
Id(ID),
211
+
// Ignored `enum` variants naturally doesn't require `Default` implementation or
212
+
// `default` value being specified, as they're just never constructed from an input.
0 commit comments