Skip to content

Commit 492fecb

Browse files
ermadmi78ermadmi78
committed
Documentation for GraphQL Schema Exploration Language (GSEL)
1 parent 39bbb2c commit 492fecb

1 file changed

Lines changed: 57 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 57 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,39 +28,56 @@ release [3.0.0](https://github.com/ermadmi78/kobby/releases/tag/3.0.0).
2828

2929
### Requirements
3030

31-
#### Kobby 4.x.x, 5.x.x
31+
* Gradle at least version 8.0 is required.
32+
* Maven at least version 3.9.1 is required.
33+
* Kotlin at least version 1.8.0 is required to compile generated client DSL (use Kobby at
34+
least [4.0.1](https://github.com/ermadmi78/kobby/releases/tag/4.0.1) for Kotlin 2.x).
35+
* Kotlinx Serialization at least version 1.5.0 is required.
36+
* Ktor at least version 2.0.0 is required to generate default adapters.
37+
* [graphql-ws](https://github.com/enisdenjo/graphql-ws) GraphQL Websocket protocol.
38+
39+
<details>
40+
<summary>Version history</summary>
41+
42+
**Kobby 4.x.x, 5.x.x**
3243

3344
* Gradle at least version 8.0 is required.
3445
* Maven at least version 3.9.1 is required.
35-
* Kotlin at least version 1.8.0 is required to compile generated client DSL (use Kobby at least [4.0.1](https://github.com/ermadmi78/kobby/releases/tag/4.0.1) for Kotlin 2.x).
46+
* Kotlin at least version 1.8.0 is required to compile generated client DSL (use Kobby at
47+
least [4.0.1](https://github.com/ermadmi78/kobby/releases/tag/4.0.1) for Kotlin 2.x).
3648
* Kotlinx Serialization at least version 1.5.0 is required.
3749
* Ktor at least version 2.0.0 is required to generate default adapters.
3850
* [graphql-ws](https://github.com/enisdenjo/graphql-ws) GraphQL Websocket protocol.
3951

40-
#### Kobby 3.x.x
52+
**Kobby 3.x.x**
4153

4254
* Gradle at least version 8.0 is required.
4355
* Maven at least version 3.9.1 is required.
4456
* Kotlin at least version 1.8.0 is required to compile generated client DSL.
4557
* Kotlinx Serialization at least version 1.5.0 is required.
4658
* Ktor at least version 2.0.0 is required to generate default adapters.
47-
* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (is legacy now).
59+
* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (
60+
is legacy now).
4861

49-
#### Kobby 2.x.x
62+
**Kobby 2.x.x**
5063

5164
* Gradle at least version 7.0 is required.
5265
* Maven at least version 3.6.3 is required.
5366
* Kotlin at least version 1.6 is required to compile generated client DSL.
5467
* Ktor at least version 2.0.0 is required to generate default adapters.
55-
* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (is legacy now).
68+
* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (
69+
is legacy now).
5670

57-
#### Kobby 1.x.x
71+
**Kobby 1.x.x**
5872

5973
* Gradle at least version 7.0 is required.
6074
* Maven at least version 3.6.3 is required.
6175
* Kotlin at least version 1.5 is required to compile generated client DSL.
6276
* 1.5.0 <= Ktor version < 2.0.0 is required to generate default adapters.
63-
* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (is legacy now).
77+
* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (
78+
is legacy now).
79+
80+
</details>
6481

6582
### Contributing
6683

@@ -106,6 +123,8 @@ schema file and put it in `src/main/resources/io/github/ermadmi78/kobby/cinema/a
106123
### Configure Kobby Gradle plugin
107124

108125
* Add Kobby plugin to your `build.gradle.kts`, to generate Kotlin DSL.
126+
* Configure the GraphQL schema location if necessary (more details
127+
see [here](https://github.com/ermadmi78/kobby/wiki/Gradle-GraphQL-Schema-Location)).
109128
* Configure Kotlin data types for scalars, defined in the GraphQL schema (more details about the scalar mapping
110129
see [here](https://github.com/ermadmi78/kobby/wiki/Gradle-GraphQL-Scalar-Mapping)).
111130
* Add Jackson dependency to enable Jackson serialization or
@@ -138,6 +157,36 @@ dependencies {
138157
}
139158
```
140159

160+
### Configure GraphQL schema truncation if necessary
161+
162+
Your does not always need all the types in the GraphQL schema. Often you works with a small subset of fields and types.
163+
To simplify code generation in such cases, the Kobby plugin provides a
164+
[mechanism for truncating the GraphQL schema](https://github.com/ermadmi78/kobby/wiki/Gradle-GraphQL-Schema-Truncation)
165+
using the [GSEL query language](https://github.com/ermadmi78/kobby/wiki/Gradle-GraphQL-Schema-Exploration-Language).
166+
167+
A simple truncation configuration looks like this:
168+
169+
```kotlin
170+
kobby {
171+
schema {
172+
truncate {
173+
byQuery {
174+
forAny {
175+
exclude {
176+
dependency("Film|Actor")
177+
subTypeDependency("Film|Actor")
178+
}
179+
}
180+
}
181+
}
182+
}
183+
}
184+
```
185+
186+
Sometimes choosing an effective GraphQL schema truncation strategy is a difficult task.
187+
And the [Kobby schema analysis tool](https://github.com/ermadmi78/kobby/wiki/Gradle-GraphQL-Schema-Analysis-Tool)
188+
can help you solve this problem.
189+
141190
### Generate Kotlin DSL Client by your GraphQL schema
142191

143192
Execute `gradle build` command to generate Kotlin DSL Client. The entry point of the DSL will be placed in

0 commit comments

Comments
 (0)