Skip to content

Commit 073d760

Browse files
dariuszkucsmyrick
dariuszkuc
authored and
smyrick
committed
[docs] updating docs to be more discoverable (ExpediaGroup#446)
1 parent aa35a1e commit 073d760

File tree

14 files changed

+784
-774
lines changed

14 files changed

+784
-774
lines changed

‎docs/writing-schemas/directives.md renamed to ‎docs/customizing-schemas/directives.md

File renamed without changes.

‎docs/customizing-schemas/documenting-fields.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
id: documenting-fields
3+
title: Documenting Schema
4+
---
5+
6+
Since Javadocs are not available at runtime for introspection, `graphql-kotlin-schema-generator` includes an annotation
7+
class `@GraphQLDescription` that can be used to add schema descriptions to *any* GraphQL schema element:
8+
9+
```kotlin
10+
@GraphQLDescription("A useful widget")
11+
data class Widget(
12+
@GraphQLDescription("The widget's value that can be null")
13+
val value: Int?
14+
)
15+
16+
class WidgetQuery: Query {
17+
18+
@GraphQLDescription("creates new widget for given ID")
19+
fun widgetById(@GraphQLDescription("The special ingredient") id: Int): Widget? = Widget(id)
20+
}
21+
```
22+
23+
The above query would produce the following GraphQL schema:
24+
25+
```graphql
26+
schema {
27+
query: Query
28+
}
29+
30+
type Query {
31+
"""creates new widget for given ID"""
32+
widgetById(
33+
"""The special ingredient"""
34+
id: Int!
35+
): Widget
36+
}
37+
38+
"""A useful widget"""
39+
type Widget {
40+
"""The widget's value that can be null"""
41+
value: Int
42+
}
43+
```

‎docs/customizing-schemas/evolving-schema.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
id: evolving-schema
3+
title: Evolving Schema
4+
---
5+
6+
### Deprecating Fields
7+
8+
GraphQL schemas can have fields marked as deprecated. Instead of creating a custom annotation,
9+
`graphql-kotlin-schema-generator` just looks for the `kotlin.Deprecated` annotation and will use that annotation message
10+
for the deprecated reason.
11+
12+
```kotlin
13+
class SimpleQuery {
14+
@Deprecated(message = "this query is deprecated", replaceWith = ReplaceWith("shinyNewQuery"))
15+
@GraphQLDescription("old query that should not be used always returns false")
16+
fun simpleDeprecatedQuery(): Boolean = false
17+
18+
@GraphQLDescription("new query that always returns true")
19+
fun shinyNewQuery(): Boolean = true
20+
}
21+
```
22+
23+
The above query would produce the following GraphQL schema:
24+
25+
```graphql
26+
schema {
27+
query: Query
28+
}
29+
30+
type Query {
31+
32+
"""old query that should not be used always returns false"""
33+
simpleDeprecatedQuery: Boolean! @deprecated(reason: "this query is deprecated, replace with shinyNewQuery")
34+
35+
"""new query that always returns true"""
36+
shinyNewQuery: Boolean!
37+
}
38+
```
39+
40+
While you can deprecate any fields/functions/classes in your Kotlin code, GraphQL only supports deprecation directive on
41+
the fields (which correspond to Kotlin fields and functions) and enum values.
42+

‎docs/customizing-schemas/excluding-fields.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
id: excluding-fields
3+
title: Excluding Fields
4+
---
5+
6+
There are two ways to ensure the GraphQL schema generation omits fields when using Kotlin reflection:
7+
8+
* The first is by marking the field as non-`public` scope (`private`, `protected`, `internal`)
9+
* The second method is by annotating the field with `@GraphQLIgnore`.
10+
11+
```kotlin
12+
class SimpleQuery {
13+
@GraphQLIgnore
14+
fun notPartOfSchema() = "ignore me!"
15+
16+
private fun privateFunctionsAreNotVisible() = "ignored private function"
17+
18+
fun doSomething(value: Int): Boolean = true
19+
}
20+
```
21+
22+
The above query would produce the following GraphQL schema:
23+
24+
```graphql
25+
schema {
26+
query: Query
27+
}
28+
29+
type Query {
30+
doSomething(value: Int!): Boolean!
31+
}
32+
```
33+
34+
Note that the public method `notPartOfSchema` is not included in the schema.

‎docs/writing-schemas/generator-config.md renamed to ‎docs/customizing-schemas/generator-config.md

Lines changed: 67 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,67 @@
1-
---
2-
id: generator-config
3-
title: Schema Generator Configuration
4-
---
5-
6-
`graphql-kotlin-schema-generator` provides a single function, `toSchema,` to generate a schema from Kotlin objects. This
7-
function accepts four arguments: config, queries, mutations and subscriptions. The queries, mutations and subscriptions
8-
are a list of
9-
[TopLevelObjects](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/TopLevelObject.kt)
10-
and will be used to generate corresponding GraphQL root types. The
11-
[config](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/SchemaGeneratorConfig.kt)
12-
contains all the extra information you need to pass, including custom hooks, supported packages and name overrides.
13-
`SchemaGeneratorConfig` has some default settings but you can override them and add custom behaviors for generating your
14-
schema.
15-
16-
* `supportedPackages` **[Required]** - List of Kotlin packages that can contain schema objects. Limits the scope of
17-
packages that can be scanned using reflections.
18-
* `topLevelNames` _[Optional]_ - Set the name of the top level GraphQL fields, defaults to `Query`, `Mutation` and
19-
`Subscription`
20-
* `hooks` _[Optional]_ - Set custom behaviors for generating the schema, see below for details.
21-
* `dataFetcherFactory` _[Optional]_ - Sets custom behavior for generating data fetchers
22-
23-
## Schema generator hooks
24-
25-
Hooks are lifecycle events that are called and triggered while the schema is building that allow users to customize the
26-
schema.
27-
28-
For exact names and details of every hook, see the comments and descriptions in our latest
29-
[javadocs](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-schema-generator) or directly in the source file:
30-
[SchemaGeneratorHooks.kt](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/hooks/SchemaGeneratorHooks.kt)
31-
32-
As an example here is how you would write a custom hook and provide it through the configuration
33-
34-
```kotlin
35-
class MyCustomHooks : SchemaGeneratorHooks {
36-
// Only generate functions that start with "dog"
37-
// This would probably be better just to use @GraphQLIgnore, but this is just an example
38-
override fun isValidFunction(function: KFunction<*>) = function.name.startsWith("dog")
39-
}
40-
41-
class Query {
42-
fun dogSound() = "bark"
43-
44-
fun catSound() = "meow"
45-
}
46-
47-
val config = SchemaGeneratorConfig(supportedPackages = listOf("org.example"), hooks = MyCustomHooks())
48-
49-
val queries = listOf(TopLevelObject(Query()))
50-
51-
toSchema(queries = queries, config = config)
52-
```
53-
54-
will generate
55-
56-
```graphql
57-
58-
schema {
59-
query: Query
60-
}
61-
62-
type Query {
63-
dogSound: String!
64-
}
65-
```
66-
67-
Notice there is no `catSound` function.
1+
---
2+
id: generator-config
3+
title: Generator Configuration
4+
---
5+
6+
`graphql-kotlin-schema-generator` provides a single function, `toSchema,` to generate a schema from Kotlin objects. This
7+
function accepts four arguments: config, queries, mutations and subscriptions. The queries, mutations and subscriptions
8+
are a list of
9+
[TopLevelObjects](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/TopLevelObject.kt)
10+
and will be used to generate corresponding GraphQL root types. The
11+
[config](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/SchemaGeneratorConfig.kt)
12+
contains all the extra information you need to pass, including custom hooks, supported packages and name overrides.
13+
`SchemaGeneratorConfig` has some default settings but you can override them and add custom behaviors for generating your
14+
schema.
15+
16+
* `supportedPackages` **[Required]** - List of Kotlin packages that can contain schema objects. Limits the scope of
17+
packages that can be scanned using reflections.
18+
* `topLevelNames` _[Optional]_ - Set the name of the top level GraphQL fields, defaults to `Query`, `Mutation` and
19+
`Subscription`
20+
* `hooks` _[Optional]_ - Set custom behaviors for generating the schema, see below for details.
21+
* `dataFetcherFactory` _[Optional]_ - Sets custom behavior for generating data fetchers
22+
23+
## Schema generator hooks
24+
25+
Hooks are lifecycle events that are called and triggered while the schema is building that allow users to customize the
26+
schema.
27+
28+
For exact names and details of every hook, see the comments and descriptions in our latest
29+
[javadocs](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-schema-generator) or directly in the source file:
30+
[SchemaGeneratorHooks.kt](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/hooks/SchemaGeneratorHooks.kt)
31+
32+
As an example here is how you would write a custom hook and provide it through the configuration
33+
34+
```kotlin
35+
class MyCustomHooks : SchemaGeneratorHooks {
36+
// Only generate functions that start with "dog"
37+
// This would probably be better just to use @GraphQLIgnore, but this is just an example
38+
override fun isValidFunction(function: KFunction<*>) = function.name.startsWith("dog")
39+
}
40+
41+
class Query {
42+
fun dogSound() = "bark"
43+
44+
fun catSound() = "meow"
45+
}
46+
47+
val config = SchemaGeneratorConfig(supportedPackages = listOf("org.example"), hooks = MyCustomHooks())
48+
49+
val queries = listOf(TopLevelObject(Query()))
50+
51+
toSchema(queries = queries, config = config)
52+
```
53+
54+
will generate
55+
56+
```graphql
57+
58+
schema {
59+
query: Query
60+
}
61+
62+
type Query {
63+
dogSound: String!
64+
}
65+
```
66+
67+
Notice there is no `catSound` function.

‎docs/customizing-schemas/renaming-fields.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
id: renaming-fields
3+
title: Renaming Fields
4+
---
5+
6+
By default, schema generator will use simple name of the underlying class for the type names and function/property names for field names.
7+
You can change this default behavior by annotating target class/field with `@GraphQLName` annotation. The following Kotlin `Widget` class
8+
will be renamed to `MyCustomName` GraphQL type.
9+
10+
```kotlin
11+
@GraphQLName("MyCustomName")
12+
data class Widget(val value: Int?)
13+
```
14+
15+
```graphql
16+
type MyCustomName {
17+
value: Int
18+
}
19+
```

‎docs/execution/contextual-data.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
id: contextual-data
3+
title: Contextual Data
4+
---
5+
6+
All GraphQL servers have a concept of a "context". A GraphQL context contains metadata that is useful to the GraphQL
7+
server, but shouldn't necessarily be part of the GraphQL query's API. A prime example of something that is appropriate
8+
for the GraphQL context would be trace headers for an OpenTracing system such as
9+
[Haystack](https://expediadotcom.github.io/haystack). The GraphQL query itself does not need the information to perform
10+
its function, but the server itself needs the information to ensure observability.
11+
12+
The contents of the GraphQL context vary across applications and it is up to the GraphQL server developers to decide
13+
what it should contain. For Spring based applications, `graphql-kotlin-spring-server` provides a simple mechanism to
14+
build context per query execution through
15+
[GraphQLContextFactory](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/GraphQLContextFactory.kt).
16+
Once context factory bean is available in the Spring application context it will then be used in a corresponding
17+
[ContextWebFilter](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-spring-server/src/main/kotlin/com/expediagroup/graphql/spring/execution/ContextWebFilter.kt)
18+
to populate GraphQL context based on the incoming request and make it available during query execution.
19+
20+
Once your application is configured to build your custom `MyGraphQLContext`, simply add `@GraphQLContext` annotation to
21+
any function argument and the corresponding GraphQL context from the environment will be automatically injected during
22+
execution.
23+
24+
```kotlin
25+
class ContextualQuery {
26+
27+
fun contextualQuery(
28+
value: Int,
29+
@GraphQLContext context: MyGraphQLContext
30+
): ContextualResponse = ContextualResponse(value, context.myCustomValue)
31+
}
32+
```
33+
34+
The above query would produce the following GraphQL schema:
35+
36+
```graphql
37+
schema {
38+
query: Query
39+
}
40+
41+
type Query {
42+
contextualQuery(
43+
value: Int!
44+
): ContextualResponse!
45+
}
46+
```
47+
48+
Note that the `@GraphQLContext` annotated argument is not reflected in the GraphQL schema.

0 commit comments

Comments
 (0)