From 78c681504f7c09bd4e81b3f0ce62cff11339f482 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bernd=20St=C3=BCbinger?= <41049452+stuebingerb@users.noreply.github.com> Date: Mon, 2 Dec 2024 14:35:39 +0100 Subject: [PATCH] docs: Cleanup documentation Fixes some incorrect links, unused files and incomplete documentation. --- docs/content/Examples/index.md | 2 +- docs/content/Plugins/ktor.md | 8 +- .../data-loader-properties.md | 119 ------------------ .../extension-properties.md | 21 ---- .../kotlin-properties.md | 24 ---- .../Objects and Interfaces/overview.md | 57 --------- .../union-properties.md | 35 ------ docs/content/Reference/Type System/enums.md | 2 +- .../Type System/objects-and-interfaces.md | 10 +- docs/content/Reference/configuration.md | 24 ++-- docs/content/Reference/operations.md | 10 +- docs/content/Reference/resolver.md | 5 +- 12 files changed, 32 insertions(+), 285 deletions(-) delete mode 100644 docs/content/Reference/Type System/Objects and Interfaces/data-loader-properties.md delete mode 100644 docs/content/Reference/Type System/Objects and Interfaces/extension-properties.md delete mode 100644 docs/content/Reference/Type System/Objects and Interfaces/kotlin-properties.md delete mode 100644 docs/content/Reference/Type System/Objects and Interfaces/overview.md delete mode 100644 docs/content/Reference/Type System/Objects and Interfaces/union-properties.md diff --git a/docs/content/Examples/index.md b/docs/content/Examples/index.md index e8b72458..ce7ba74b 100644 --- a/docs/content/Examples/index.md +++ b/docs/content/Examples/index.md @@ -1,7 +1,7 @@ Here you can find some example projects using this library: 1. Basic example using the ktor - plugin: [Official Example](https://github.com/stuebingerb/KGraphQL/tree/main/kgraphql-example) + plugin: [Official Example](https://github.com/stuebingerb/KGraphQL/tree/main/examples/ktor) 1. Todo app that allows for nested todos and different scopes: [Todo Tree](https://github.com/MattLangsenkamp/TodoTree) 1. An article about pairing Kotlin and GraphQL together using http4k [Medium Article](https://medium.com/@pagakrivos/graphql-and-kotlin-e5d17162d169) | [GitHub repo](https://github.com/pagidas/kgraphql-http4k-demo) diff --git a/docs/content/Plugins/ktor.md b/docs/content/Plugins/ktor.md index 32b0b95b..a3aa7f3b 100644 --- a/docs/content/Plugins/ktor.md +++ b/docs/content/Plugins/ktor.md @@ -46,21 +46,21 @@ test it out directly within the browser. ## Configuration options -The GraphQL feature is extending the standard [KGraphQL configuration](/Reference/configuration) and providing its own +The GraphQL feature is extending the standard [KGraphQL configuration](../Reference/configuration.md) and providing its own set of configuration as described in the table below. | Property | Description | Default value | |------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------| -| playground | Gives you out of the box access to a [GraphQL playground](https://github.com/graphql/graphiql) | `false` | +| playground | Gives you out of the box access to a [GraphQL playground](https://github.com/graphql/graphiql) | `false` | | endpoint | This specifies what route will be delivering the GraphQL endpoint. When `playground` is enabled, it will use this endpoint also. | `/graphql` | | context | Refer to example below | | | wrap | If you want to wrap the route into something before KGraphQL will install the GraphQL route. You can use this wrapper. See example below for a more in depth on how to use it. | | -| schema | This is where you are defining your schema. Please refer to [KGraphQL References](/Reference/operations) for further documentation on this. | ***required*** | +| schema | This is where you are defining your schema. Please refer to [KGraphQL References](../Reference/operations.md) for further documentation on this. | ***required*** | ### Wrap Sometimes you would need to wrap your route within something. A good example of this would be the `authenticate` -function provided by [ktor Authentication feature](https://ktor.io/servers/features/authentication.html). +function provided by [ktor Authentication feature](https://ktor.io/docs/server-auth.html). ```kotlin wrap { diff --git a/docs/content/Reference/Type System/Objects and Interfaces/data-loader-properties.md b/docs/content/Reference/Type System/Objects and Interfaces/data-loader-properties.md deleted file mode 100644 index 36c00cf4..00000000 --- a/docs/content/Reference/Type System/Objects and Interfaces/data-loader-properties.md +++ /dev/null @@ -1,119 +0,0 @@ -*This feature is still in experimental state.* - -One issue that you could easily encounter when doing a GraphQL API is the N+1 Problem. You can read more about this -problem and solution in depth -here: [The GraphQL Dataloader Pattern: Visualized](https://medium.com/@__xuorig__/the-graphql-dataloader-pattern-visualized-3064a00f319f) - -Imagine having this query: - -```graphql -{ - people(first: 10) { - name - friends(first: 5) { - name - } - } -} -``` - -Running this against a Database would execute 11 SQL queries: -First fetch the 10 people. Then loop through each of them and fetch their first 5 friends one by one. - -While what we would like is to fetch the first 10 people in 1 SQL and then fetch the first 5 friends for all those 10 -people in the second query. That's what the `dataProperty` will solve for you. - -## Setting up - -Using DataLoaders requires the `DataLoaderPrepared` executor: - -```kotlin -configure { - executor = Executor.DataLoaderPrepared -} -``` - -*Example* - -```kotlin -data class Person(val id: Int, val name: String) -val people = (1..5).map { Person(it, "Name-$it") } -... -configure { - executor = Executor.DataLoaderPrepared -} -query("people") { - resolver { -> people } -} -type { - // Int - defines the key that will be sent from the [prepare] into [loader] - // Person? - defines the return type that the [loader] is required to return. - // the loader is then required to return it in a map format like Map - dataProperty("nextPerson") { - prepare { person, skipAmount: Int -> person.id + skipAmount } - loader { ids -> - ids.map { - ExecutionResult.Success(people[it-1]) - } - } - } -} -``` - -*GraphQL Query example:* - -```graphql -{ - people { - name - nextPerson(skipAmount: 2) { - name - } - } -} -``` - -Returns: - -```json -{ - "data": { - "people": [ - { - "name": "Name-1", - "nextPerson": { - "name": "Name-3" - } - }, - { - "name": "Name-2", - "nextPerson": { - "name": "Name-4" - } - }, - { - "name": "Name-3", - "nextPerson": { - "name": "Name-5" - } - }, - { - "name": "Name-4", - "nextPerson": null - }, - { - "name": "Name-5", - "nextPerson": null - } - ] - } -} -``` - -## Current known issues - -This feature can be used in production but does currently have some issues: - -1. The `useDefaultPrettyPrint` doesn't work. -1. Order of fields are not guaranteed, to match the order that was requested -1. Other than that it should work as expected. diff --git a/docs/content/Reference/Type System/Objects and Interfaces/extension-properties.md b/docs/content/Reference/Type System/Objects and Interfaces/extension-properties.md deleted file mode 100644 index 72b57d33..00000000 --- a/docs/content/Reference/Type System/Objects and Interfaces/extension-properties.md +++ /dev/null @@ -1,21 +0,0 @@ -Extension properties allow schema creator to easily attach additional field to any type. It is separately evaluated -after main entity is resolved. - -## property { } - -`property` method accepts [resolver](/docs/reference/resolver) and can be subject -of [deprecation](/docs/reference/deprecation). - -*Example* - -```kotlin -data class Person(val name: String, val age: Int) - -KGraphQL.schema { - type { - property("isChild") { - resolver { person -> person.age <= 18 } - } - } -} -``` diff --git a/docs/content/Reference/Type System/Objects and Interfaces/kotlin-properties.md b/docs/content/Reference/Type System/Objects and Interfaces/kotlin-properties.md deleted file mode 100644 index 692171dd..00000000 --- a/docs/content/Reference/Type System/Objects and Interfaces/kotlin-properties.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Kotlin Properties -weight: 1 ---- - -Kotlin properties are automatically inspected during schema creation. Schema DSL allows ignoring -and [deprecation](/docs/reference/deprecation) of kotlin properties. - -*Example* - -```kotlin -data class Person(val name: String, val age: Int) - -KGraphQL.schema { - type { - property(Person::age) { - ignore = true - } - property(Person::name) { - deprecate("Person needs no name") - } - } -} -``` diff --git a/docs/content/Reference/Type System/Objects and Interfaces/overview.md b/docs/content/Reference/Type System/Objects and Interfaces/overview.md deleted file mode 100644 index faa24282..00000000 --- a/docs/content/Reference/Type System/Objects and Interfaces/overview.md +++ /dev/null @@ -1,57 +0,0 @@ -GraphQL Objects and Interfaces represent a list of named fields, each of which yield a value of a specific type. -KGraphQL inspects defined operations to create type system, but schema creator is able to explicitly declare and -customize types. Besides, only member properties are inspected. - -## type { } - -`type` method is entry point to Type DSL. -See [Extension Properties](/docs/reference/type-system/objects-and-interfaces/extension-properties), [Kotlin Properties](/docs/reference/type-system/objects-and-interfaces/kotlin-properties), [Union Properties](/docs/reference/type-system/objects-and-interfaces/union-properties). - -*Example* - -```kotlin -data class Person(val name: String, val age: Int) - -KGraphQL.schema { - type { - description = "Human" - } -} -``` - -## KProperty1.ignore - -extension function `ignore()` makes KGraphQL ignore its receiver property. - -*Example* - -```kotlin -data class Person(val name: String, val age: Int) - -KGraphQL.schema { - type { - Person::age.ignore() - } -} -``` - -## transformation(KProperty1) {} - -`transformation` method allows schema creator to attach data transformation on any kotlin property of type. Like -operations, `transformation` has property `resolver` which is used to declare data transformation. - -*Example* - -```kotlin -data class Person(val name: String, val age: Int) - -KGraphQL.schema { - type { - transformation(Person::age) { - // inMonths is nullable, so client can fetch age property without passing any value to this argument - // if(null == true) evaluates to false, if(null) is invalid kotlin code - age: Int, inMonths: Boolean? -> if (inMonths == true) { age * 12 } else { age } - } - } -} -``` diff --git a/docs/content/Reference/Type System/Objects and Interfaces/union-properties.md b/docs/content/Reference/Type System/Objects and Interfaces/union-properties.md deleted file mode 100644 index 4e9107ac..00000000 --- a/docs/content/Reference/Type System/Objects and Interfaces/union-properties.md +++ /dev/null @@ -1,35 +0,0 @@ -As Kotlin does not support unions, union properties have to be explicitly declared in Schema DSL. Creating union -property requires defining [resolver](/docs/reference/resolver) and return type. Return Type is reference returned by -creation of [union type](/docs/reference/type-system/unions). - -Union type resolver is not type checked. Invalid resolver implementation which would return value of type other than -members of union type will fail in runtime. - -*Example* - -```kotlin -data class UnionMember1(val one: String) - -data class UnionMember2(val two: String) - -data class Person(val name: String, val age: Int) - -KGraphQL.schema { - type { - unionProperty("union") { - nullable = true // Defaults to false - returnType = unionType("UnionExample") { - type() - type() - } - resolver { person -> - if (person.age <= 18) { - UnionMember1("one") - } else { - UnionMember2("two") - } - } - } - } -} -``` diff --git a/docs/content/Reference/Type System/enums.md b/docs/content/Reference/Type System/enums.md index 5c28a018..559cd5f7 100644 --- a/docs/content/Reference/Type System/enums.md +++ b/docs/content/Reference/Type System/enums.md @@ -24,7 +24,7 @@ val schema = KGraphQL.schema { } ``` -Enum values can be [deprecated](/Reference/deprecation): +Enum values can be [deprecated](../deprecation.md): *Example* diff --git a/docs/content/Reference/Type System/objects-and-interfaces.md b/docs/content/Reference/Type System/objects-and-interfaces.md index a46f3bbb..46536073 100644 --- a/docs/content/Reference/Type System/objects-and-interfaces.md +++ b/docs/content/Reference/Type System/objects-and-interfaces.md @@ -6,7 +6,7 @@ customize types. Besides, only member properties are inspected. **type { }** `type` method is entry point to Type DSL. -See [Extension Properties](/Reference/Type%20System/objects-and-interfaces/#extension-properties), [Kotlin Properties](/Reference/Type%20System/objects-and-interfaces/#kotlin-properties), [Union Properties](/Reference/Type%20System/objects-and-interfaces/#union-properties). +See [Extension Properties](#extension-properties), [Kotlin Properties](#kotlin-properties), [Union Properties](#union-properties). *Example* @@ -59,7 +59,7 @@ KGraphQL.schema { ## Kotlin Properties Kotlin properties are automatically inspected during schema creation. Schema DSL allows ignoring -and [deprecation](/Reference/deprecation) of kotlin properties +and [deprecation](../deprecation.md) of kotlin properties *Example* @@ -85,7 +85,7 @@ after main entity is resolved. ## property { } -`property` method accepts [resolver](/Reference/resolver) and can be subject of [deprecation](/Reference/deprecation). +`property` method accepts [resolver](../resolver.md) and can be subject of [deprecation](../deprecation.md). *Example* @@ -104,8 +104,8 @@ KGraphQL.schema { ## Union Properties As Kotlin does not support unions, union properties have to be explicitly declared in Schema DSL. Creating union -property requires defining [resolver](/Reference/resolver) and return type. Return Type is reference returned by -creation of [union type](/Reference/Type%20System/unions/). +property requires defining [resolver](../resolver.md) and return type. Return Type is reference returned by +creation of [union type](unions.md). Union type resolver is not type checked. Invalid resolver implementation which would return value of type other than members of union type will fail in runtime. diff --git a/docs/content/Reference/configuration.md b/docs/content/Reference/configuration.md index d7905e81..8613a401 100644 --- a/docs/content/Reference/configuration.md +++ b/docs/content/Reference/configuration.md @@ -1,15 +1,19 @@ KGraphQL schema allows configuration of the following properties: -| Property | Description | Default value | -|--------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| useDefaultPrettyPrinter | Schema pretty prints JSON reponses | `false` | -| useCachingDocumentParser | Schema caches parsed query documents | `true` | -| documentParserCacheMaximumSize | Schema document cache maximum size | `1000` | -| objectMapper | Schema is using Jackson ObjectMapper from this property | result of `jacksonObjectMapper()` from [jackson-kotlin-module](https://github.com/FasterXML/jackson-module-kotlin) | -| acceptSingleValueAsArray | Schema accepts single argument values as singleton list | `true` | -| coroutineDispatcher | Schema is using CoroutineDispatcher from this property | [CommonPool](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CommonPool.kt) | -| executor | | [Executor.Parallel](https://github.com/aPureBase/KGraphQL/blob/master/kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/execution/Executor.kt) | -| genericTypeResolver | Schema is using generic type resolver from this property | [GenericTypeResolver.DEFAULT](https://github.com/aPureBase/KGraphQL/blob/master/kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/execution/GenericTypeResolver.kt) | +| Property | Description | Default value | +|--------------------------------|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| useDefaultPrettyPrinter | Schema pretty prints JSON responses | `false` | +| useCachingDocumentParser | Schema caches parsed query documents | `true` | +| documentParserCacheMaximumSize | Schema document cache maximum size | `1000` | +| objectMapper | Schema is using Jackson ObjectMapper from this property | result of `jacksonObjectMapper()` from [jackson-kotlin-module](https://github.com/FasterXML/jackson-module-kotlin) | +| acceptSingleValueAsArray | Schema accepts single argument values as singleton list | `true` | +| coroutineDispatcher | Schema is using CoroutineDispatcher from this property | [CommonPool](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CommonPool.kt) | +| executor | | [Executor.Parallel](https://github.com/aPureBase/KGraphQL/blob/master/kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/execution/Executor.kt) | +| genericTypeResolver | Schema is using generic type resolver from this property | [GenericTypeResolver.DEFAULT](https://github.com/aPureBase/KGraphQL/blob/master/kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/execution/GenericTypeResolver.kt) | +| wrapErrors | | `true` | +| timeout | | `null` | +| introspection | Schema allows introspection (also affects SDL). Introspection can be disabled in production to reduce attack surface. | `true` | +| plugins | (unused?) | | *Example* diff --git a/docs/content/Reference/operations.md b/docs/content/Reference/operations.md index 64d470bb..8b0a3d1f 100644 --- a/docs/content/Reference/operations.md +++ b/docs/content/Reference/operations.md @@ -12,14 +12,14 @@ Each operation is represented by an operation name and a selection set. In KGraphQL, operation is declared in `SchemaBuilder` block. Every operation has 2 properties: -| name | description | -|----------|---------------------------------| -| name | name of operation | -| resolver | [Resolver](/Reference/resolver) | +| name | description | +|----------|-------------------------| +| name | name of operation | +| resolver | [Resolver](resolver.md) | Selection set is automatically created based on resolver return type. By default, selection set for specific class contains all its member properties (without extension properties), but it can be customized (TBD Type wiki page). -Operations can be [deprecated](/Reference/deprecation) +Operations can be [deprecated](deprecation.md) Subscription is not supported yet. diff --git a/docs/content/Reference/resolver.md b/docs/content/Reference/resolver.md index f39b3958..731f908b 100644 --- a/docs/content/Reference/resolver.md +++ b/docs/content/Reference/resolver.md @@ -3,9 +3,8 @@ ## Basics In GraphQL every property needs a resolver. The resolver is the piece of system logic, required to resolve the response -graph. [Operations](/Reference/operations), [](/Reference/) -Resolver is KGraphQL definition of piece of system logic, required to resolve response graph. Operations, Extension -Properties and Union Properties accept resolver, which allows schema creator to configure schema behaviour. +graph. [Operations](operations.md), [Extension +Properties](Type%20System/objects-and-interfaces.md/#extension-properties) and [Union Properties](Type%20System/unions.md) accept resolver, which allows schema creator to configure schema behaviour. Resolver clause accepts kotlin function and returns its DSL item, which is entry point for additional customization of resolver