Skip to content

Commit 3abbda2

Browse files
dariuszkucdariuszkuc
authored
[docs] cut documentation version for 3.x.x releases (ExpediaGroup#807)
As we prepare to start working on v4.x.x features on master we are cutting current documentation version
1 parent 359e0fc commit 3abbda2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+4013
-0
lines changed

‎website/pages/en/versions.js

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
/**
2+
* Copyright (c) 2017-present, Facebook, Inc.
3+
*
4+
* This source code is licensed under the MIT license found in the
5+
* LICENSE file in the root directory of this source tree.
6+
*/
7+
8+
const React = require('react');
9+
10+
const CompLibrary = require('../../core/CompLibrary');
11+
12+
const Container = CompLibrary.Container;
13+
14+
const CWD = process.cwd();
15+
16+
const versions = require(`${CWD}/versions.json`);
17+
18+
function Versions(props) {
19+
const {config: siteConfig} = props;
20+
const latestVersion = versions[0];
21+
const repoUrl = `https://github.com/${siteConfig.organizationName}/${siteConfig.projectName}`;
22+
return (
23+
<div className="docMainWrapper wrapper">
24+
<Container className="mainContainer versionsContainer">
25+
<div className="post">
26+
<header className="postHeader">
27+
<h1>{siteConfig.title} Versions</h1>
28+
</header>
29+
<h3 id="latest">Current version (Stable)</h3>
30+
<table className="versions">
31+
<tbody>
32+
<tr>
33+
<th>{latestVersion}</th>
34+
<td>
35+
<a
36+
href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/getting-started.html`}>
37+
Documentation
38+
</a>
39+
</td>
40+
<td>
41+
<a href={`${repoUrl}/releases`}>Release Notes</a>
42+
</td>
43+
</tr>
44+
</tbody>
45+
</table>
46+
47+
<h3 id="rc">Pre-release versions</h3>
48+
<table className="versions">
49+
<tbody>
50+
<tr>
51+
<th>master</th>
52+
<td>
53+
{/* You are supposed to change this href where appropriate
54+
Example: href="<baseUrl>/docs(/:language)/next/:id" */}
55+
<a
56+
href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/next/getting-started.html`}>
57+
Documentation
58+
</a>
59+
</td>
60+
<td>
61+
<a href={repoUrl}>Source Code</a>
62+
</td>
63+
</tr>
64+
</tbody>
65+
</table>
66+
67+
{/* TODO uncomment below once we release 4.x.x
68+
<h3 id="archive">Past Versions</h3>
69+
<p>Here you can find previous versions of the documentation.</p>
70+
<table className="versions">
71+
<tbody>
72+
{versions.map(
73+
version =>
74+
version !== latestVersion && (
75+
<tr key={version}>
76+
<th>{version}</th>
77+
<td>
78+
<a
79+
href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/${
80+
props.language ? props.language + '/' : ''
81+
}${version}/doc1`}>
82+
Documentation
83+
</a>
84+
</td>
85+
<td>
86+
<a href={`${repoUrl}/releases/tag/v${version}`}>
87+
Release Notes
88+
</a>
89+
</td>
90+
</tr>
91+
),
92+
)}
93+
</tbody>
94+
</table>
95+
<p>
96+
You can find past versions of this project on{' '}
97+
<a href={repoUrl}>GitHub</a>.
98+
</p>
99+
*/}
100+
</div>
101+
</Container>
102+
</div>
103+
);
104+
}
105+
106+
module.exports = Versions;

‎website/versioned_docs/version-3.4.1/blogs-and-videos.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
id: version-3.4.1-blogs-and-videos
3+
title: Blogs & Videos
4+
original_id: blogs-and-videos
5+
---
6+
7+
Here are some links to other blog posts and videos which may provide further examples and reading.
8+
9+
## graphql-kotlin
10+
Articles and videos specifically about `graphql-kotlin`
11+
12+
* 📝&nbsp;&nbsp;[Introducing GraphQL Kotlin Client](https://medium.com/expedia-group-tech/introducing-graphql-kotlin-client-b32dc3061a6f)
13+
* 📝&nbsp;&nbsp;[Announcing graphql-kotlin 2.0!](https://medium.com/expedia-group-tech/graphql-kotlin-2-0-4006ea41f774)
14+
* 📺&nbsp;&nbsp;[Bootiful GraphQL with Kotlin (Dariusz Kuc, Guillaume Scheibel)](https://www.youtube.com/watch?v=7YJyPXjLdug&amp;index=25) (en)
15+
* 📝&nbsp;&nbsp;[Creating a Reactive GraphQL Server with Spring Boot and Kotlin](https://medium.com/expedia-group-tech/creating-a-reactive-graphql-server-with-spring-boot-and-kotlin-54aca7316470)
16+
* 📝&nbsp;&nbsp;[Apollo Federation in a GraphQL Kotlin Server](https://medium.com/expedia-group-tech/apollo-federation-in-a-graphql-kotlin-server-115cea51607a)
17+
* 📝&nbsp;&nbsp;[Creating GraphQL Schemas in Kotlin](https://medium.com/expedia-group-tech/creating-graphql-schemas-in-kotlin-aaaac0ab0672)
18+
* 📝&nbsp;&nbsp;[Release of graphql-kotlin 1.0.0!](https://medium.com/expedia-group-tech/release-of-graphql-kotlin-1-0-0-791ad85d3116)
19+
* 📝&nbsp;&nbsp;[graphql-kotlin: Generate a GraphQL schema from Kotlin code](https://medium.com/expedia-group-tech/graphql-kotlin-generate-a-graphql-schema-from-kotlin-code-21d1dc2f6e27)
20+
21+
## GraphQL
22+
Articles and videos about how Expedia Group is using GraphQL
23+
24+
* 📺&nbsp;&nbsp;[Creating a federated schema for a global company (Shane Myrick)](https://youtu.be/MuD3TAP0D9Y) (en)
25+
* 📺&nbsp;&nbsp;[Migrer ses APIs vers GraphQL: pourquoi? comment! (Guillaume Scheibel)](https://youtu.be/IRIkpvJo95s) (fr)
26+
* 📺&nbsp;&nbsp;[Migrate your APIs to GraphQL: how? and why! (Guillaume Scheibel)](https://youtu.be/IkPMpzQ-TRI) (en)
27+
* 📺&nbsp;&nbsp;[Transforming customer experiences and your organization with GraphQL (Jim Gust, Dan Boerner)](https://youtu.be/Jt-ZD4zj4Ow) (en)

‎website/versioned_docs/version-3.4.1/client/client-customization.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
id: version-3.4.1-client-customization
3+
title: Client Customization
4+
original_id: client-customization
5+
---
6+
7+
## Ktor HTTP Client Customization
8+
9+
`GraphQLClient` uses the Ktor HTTP Client to execute the underlying queries. Clients can be customized with different
10+
engines (defaults to Coroutine-based IO) and HTTP client features. Custom configurations can be applied through Ktor DSL
11+
style builders.
12+
13+
See [Ktor HTTP Client documentation](https://ktor.io/clients/index.html) for additional details.
14+
15+
### Global Client Customization
16+
17+
A single instance of `GraphQLClient` can be used to power many GraphQL operations. You can specify a target engine factory and
18+
configure it through the corresponding [HttpClientConfig](https://api.ktor.io/1.3.2/io.ktor.client/-http-client-config/index.html).
19+
Ktor also provides a number of [standard HTTP features](https://ktor.io/clients/http-client/features.html) and
20+
allows you to easily create custom ones that can be configured globally.
21+
22+
The below example configures a new `GraphQLClient` to use the `OkHttp` engine with custom timeouts, adds a default `X-MY-API-KEY`
23+
header to all requests, and enables basic logging of the requests.
24+
25+
```kotlin
26+
val client = GraphQLClient(
27+
url = URL("http://localhost:8080/graphql"),
28+
engineFactory = OkHttp
29+
) {
30+
engine {
31+
config {
32+
connectTimeout(10, TimeUnit.SECONDS)
33+
readTimeout(60, TimeUnit.SECONDS)
34+
writeTimeout(60, TimeUnit.SECONDS)
35+
}
36+
}
37+
defaultRequest {
38+
header("X-MY-API-KEY", "someSecretApiKey")
39+
}
40+
install(Logging) {
41+
logger = Logger.DEFAULT
42+
level = LogLevel.INFO
43+
}
44+
}
45+
```
46+
47+
### Per Request Customization
48+
49+
Individual GraphQL requests can be customized through [HttpRequestBuilder](https://api.ktor.io/1.3.2/io.ktor.client.request/-http-request-builder/).
50+
You can use this mechanism to specify custom headers, update target url to include custom query parameters, configure
51+
attributes that can be accessed from the pipeline features as well specify timeouts per request.
52+
53+
```kotlin
54+
val helloWorldQuery = HelloWorldQuery(client)
55+
val result = helloWorldQuery.execute(variables = HelloWorldQuery.Variables(name = null)) {
56+
header("X-B3-TraceId", "0123456789abcdef")
57+
}
58+
```
59+
60+
## Jackson Customization
61+
62+
`GraphQLClient` relies on Jackson to handle polymorphic types and default enum values. You can specify your own custom
63+
object mapper configured with some additional serialization/deserialization features but due to the necessary logic to
64+
handle the above, currently we don't support other JSON libraries.
65+
66+
```kotlin
67+
val customObjectMapper = jacksonObjectMapper()
68+
val client = GraphQLClient(url = URL("http://localhost:8080/graphql"), mapper = customObjectMapper)
69+
```
70+
71+
## Deprecated Field Usage
72+
73+
Build plugins will automatically fail generation of a client if any of the specified query files are referencing
74+
deprecated fields. This ensures that your clients have to explicitly opt-in into deprecated usage by specifying
75+
`allowDeprecatedFields` configuration option.
76+
77+
## Custom GraphQL Scalars
78+
79+
By default, custom GraphQL scalars are serialized and [type-aliased](https://kotlinlang.org/docs/reference/type-aliases.html)
80+
to a String. GraphQL Kotlin plugins also support custom serialization based on provided configuration.
81+
82+
In order to automatically convert between custom GraphQL `UUID` scalar type and `java.util.UUID`, we first need to create
83+
our custom `ScalarConverter`.
84+
85+
```kotlin
86+
package com.example.client
87+
88+
import com.expediagroup.graphql.client.converter.ScalarConverter
89+
import java.util.UUID
90+
91+
class UUIDScalarConverter : ScalarConverter<UUID> {
92+
override fun toScalar(rawValue: String): UUID = UUID.fromString(rawValue)
93+
override fun toJson(value: UUID): String = value.toString()
94+
}
95+
```
96+
97+
And then configure build plugin by specifying
98+
* Custom GraphQL scalar name
99+
* Target class name
100+
* Converter that provides logic to map between GraphQL and Kotlin type
101+
102+
```kotlin
103+
graphql {
104+
packageName = "com.example.generated"
105+
endpoint = "http://localhost:8080/graphql"
106+
converters.put("UUID", ScalarConverterMapping("java.util.UUID", "com.example.UUIDScalarConverter"))
107+
}
108+
```
109+
110+
See [Gradle](../plugins/gradle-plugin.md)
111+
and [Maven](../plugins/maven-plugin.md)
112+
plugin documentation for additional details.

‎website/versioned_docs/version-3.4.1/client/client-features.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
id: version-3.4.1-client-features
3+
title: Client Features
4+
original_id: client-features
5+
---
6+
7+
## Polymorphic Types Support
8+
9+
GraphQL supports polymorphic types through unions and interfaces which can be represented in Kotlin as marker and
10+
regular interfaces. In order to ensure generated objects are not empty, GraphQL queries referencing polymorphic types
11+
have to **explicitly specify all implementations**. Polymorphic queries also have to explicitly request `__typename`
12+
field so it can be used to Jackson correctly distinguish between different implementations.
13+
14+
Given example schema
15+
16+
```graphql
17+
type Query {
18+
interfaceQuery: BasicInterface!
19+
}
20+
21+
interface BasicInterface {
22+
id: Int!
23+
name: String!
24+
}
25+
26+
type FirstInterfaceImplementation implements BasicInterface {
27+
id: Int!
28+
intValue: Int!
29+
name: String!
30+
}
31+
32+
type SecondInterfaceImplementation implements BasicInterface {
33+
floatValue: Float!
34+
id: Int!
35+
name: String!
36+
}
37+
```
38+
39+
We can query interface field as
40+
41+
```graphql
42+
query PolymorphicQuery {
43+
interfaceQuery {
44+
__typename
45+
id
46+
name
47+
... on FirstInterfaceImplementation {
48+
intValue
49+
}
50+
... on SecondInterfaceImplementation {
51+
floatValue
52+
}
53+
}
54+
}
55+
```
56+
57+
Which will generate following data model
58+
59+
```kotlin
60+
@JsonTypeInfo(
61+
use = JsonTypeInfo.Id.NAME,
62+
include = JsonTypeInfo.As.PROPERTY,
63+
property = "__typename"
64+
)
65+
@JsonSubTypes(value = [com.fasterxml.jackson.annotation.JsonSubTypes.Type(value =
66+
PolymorphicQuery.FirstInterfaceImplementation::class,
67+
name="FirstInterfaceImplementation"),com.fasterxml.jackson.annotation.JsonSubTypes.Type(value
68+
= PolymorphicQuery.SecondInterfaceImplementation::class, name="SecondInterfaceImplementation")])
69+
interface BasicInterface {
70+
val id: Int
71+
val name: String
72+
}
73+
74+
data class FirstInterfaceImplementation(
75+
override val id: Int,
76+
override val name: String,
77+
val intValue: Int
78+
) : PolymorphicQuery.BasicInterface
79+
80+
data class SecondInterfaceImplementation(
81+
override val id: Int,
82+
override val name: String,
83+
val floatValue: Float
84+
) : PolymorphicQuery.BasicInterface
85+
```
86+
87+
## Default Enum Values
88+
89+
Enums represent predefined set of values. Adding additional enum values could be a potentially breaking change as your
90+
clients may not be able to process it. GraphQL Kotlin Client automatically adds default `@JsonEnumDefaultValue __UNKNOWN_VALUE`
91+
to all generated enums as a catch all safeguard for handling new enum values.
92+
93+
## Auto Generated Documentation
94+
95+
GraphQL Kotlin build plugins automatically pull in GraphQL descriptions of the queried fields from the target schema and
96+
add it as KDoc to corresponding data models.
97+
98+
Given simple GraphQL object definition
99+
100+
```graphql
101+
"Some basic description"
102+
type BasicObject {
103+
"Unique identifier"
104+
id: Int!
105+
"Object name"
106+
name: String!
107+
}
108+
```
109+
110+
Will result in a corresponding auto generated data class
111+
112+
```kotlin
113+
/**
114+
* Some basic description
115+
*/
116+
data class BasicObject(
117+
/**
118+
* Unique identifier
119+
*/
120+
val id: Int,
121+
/**
122+
* Object name
123+
*/
124+
val name: String
125+
)
126+
```
127+
128+
## Native Support for Coroutines
129+
130+
GraphQL Kotlin Client is a thin wrapper on top of [Ktor HTTP Client](https://ktor.io/clients/index.html) which provides
131+
fully asynchronous communication through Kotlin coroutines. `GraphQLClient` exposes single `execute` method that will
132+
suspend your GraphQL operation until it gets a response back without blocking the underlying thread. In order to fetch
133+
data asynchronously and perform some additional computations at the same time you should wrap your client execution in
134+
`launch` or `async` coroutine builder and explicitly `await` for their results.
135+
136+
See [Kotlin coroutines documentation](https://kotlinlang.org/docs/reference/coroutines-overview.html) for additional details.

0 commit comments

Comments
 (0)