Skip to content

Commit d03cb42

Browse files
committed
chore(docs): add doubleNull and pagination documentation
1 parent b74ae0d commit d03cb42

File tree

1 file changed

+72
-4
lines changed

1 file changed

+72
-4
lines changed

docs/codegen/schema-configuration.md

Lines changed: 72 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,16 @@ directive @kRepresentation(class: String!) on OBJECT | SCALAR
1111
directive @kGenerate on OBJECT
1212

1313
# Tells the code generator that a resolver shall be generated.
14-
directive @kResolver on FIELD_DEFINITION | OBJECT | INTERFACE
14+
directive @kResolver on FIELD_DEFINITION | OBJECT | INTERFACE
15+
16+
# Tells the code generator to wrap the value into another nullable wrapper.
17+
directive @kDoubleNull on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
18+
19+
# Tells the code generator that the field definition should support pagination.
20+
directive @kPagination on FIELD_DEFINITION
1521
```
1622

17-
#### Bind object type to existing class (`@kRepresentation`)
23+
### Bind object type to existing class (`@kRepresentation`)
1824
Given the following schema:
1925
```graphql
2026
type User {
@@ -30,7 +36,7 @@ type User @kRepresentation(class: "com.auritylab.graphql.entity.User") {
3036
}
3137
```
3238

33-
#### Avoid generating all resolvers (`@kResolver`)
39+
### Avoid generating all resolvers (`@kResolver`)
3440
When building a large GraphQL API there can be a lot of resolvers. By default the code generator will generate code for every resolver.
3541
This behavior can be adjusted using the `generateAll` option (See [usage](#usage)). When setting it to `false` the code generator will only generate code if the `@kResolver` directive has been added in the schema.
3642
This is also useful as the `graphql-java` library provides a property resolver, which mostly takes most of the work.
@@ -55,7 +61,7 @@ type User {
5561
}
5662
```
5763

58-
#### Avoid generating all object types (`@kGenerate`)
64+
### Avoid generating all object types (`@kGenerate`)
5965
In GraphQL you mostly use object types to represent your data. By default the code generator will generate a `data class` for each object type if no `@kRepresentation` is given.
6066

6167
Given the following object type:
@@ -76,6 +82,68 @@ data class User(
7682
)
7783
```
7884

85+
### Double nullability (`@kDoubleNull`)
86+
Sometimes there are cases where you want to update certain data, but the attribute you want to update is nullable.
87+
88+
Given the following mutation `updateUser(name: String, surname: String)` which allows you to partially update your User.
89+
The attribute `surname` can be null within your database, which means the mutation can be called with following data:
90+
`{"name": "test", "surname": null}`.
91+
When explicitly setting the `surname` to `null` you simply tell your resolver, that you want to set the `surname` to `null`.
92+
93+
Now to the case where `@kDoubleNull` comes into play: You may never want to update the `surname` attribute, therefore you may
94+
call the mutation with the following data: `{"name": "test"}`. When not using the `@kDoubleNull` directive you get `String?`
95+
as type for the `surname` attribute, which makes it unable to differ if the user want's to explicitly set the value to `null` or simply not update it.
96+
97+
When using `@kDoubleNull` on your mutation parameter (`updateUser(name: String, surname: String @kDoubleNull)`) you get `V<String?>?` as type for the `surname` attribute.
98+
As the type is now double nullable you can differ if the value shall be set to null, or the value should not be updated at all.
99+
100+
101+
### Pagination (`@kPagination`)
102+
This code generator also supports the [GraphQL Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm) which allows you to easily implement pagination on your queries.
103+
104+
#### With [Spring Boot Integration](/docs/spring-boot-integration/getting-started.md)
105+
Simply add the `@kPagination` directive to your field definition, and the code generator and the Spring Boot Integration will do the rest for you:
106+
```graphql
107+
type Query {
108+
# ...
109+
getUsers: [User] @kPagination
110+
# ...
111+
}
112+
```
113+
114+
#### Standalone
115+
When using the code generator without the Spring Boot Integration you have to define the `*Connection`, `*Edge` and `PageInfo` types by yourself.
116+
117+
This may look like the following example:
118+
```graphql
119+
type Query {
120+
# ...
121+
getUsers(first: Int, last: Int, after: String, before: String): UserConnection @kPagination
122+
# ...
123+
}
124+
125+
type UserConnection {
126+
edges: [UserEdge]
127+
pageInfo: PageInfo!
128+
}
129+
130+
type UserEdge {
131+
node: User
132+
cursor: String!
133+
}
134+
135+
type PageInfo {
136+
hasNextPage: Boolean!
137+
hasPreviousPage: Boolean!
138+
startCursor: String!
139+
endCursor: String!
140+
}
141+
```
142+
143+
As seen in the example you have to define the `UserConnection`, `UserEdge` and the `PageInfo` (you only have to define this type once!).
144+
By adding the `@kPagination` directive you still get the easy to use field resolver generated by the code generator.
145+
146+
79147
## Disable generating code for all types
80148
As described above, it will generate code for all available types, this behavior can be controlled using the following property:
81149
```kotlin

0 commit comments

Comments
 (0)