[docs] Add server http req/res page (ExpediaGroup#773)

smyrick · Shane Myrick · dariuszkuc · web-flow · commit 798ff31046bf · 2020-06-23T22:50:06.000-05:00
* Add server http req/res page

* PR comments

* Update README.md

Co-authored-by: Dariusz Kuc &lt;dariusz_kuc@hotmail.com&gt;

* Apply suggestions from code review

Co-authored-by: Dariusz Kuc &lt;dariusz_kuc@hotmail.com&gt;

* Update http-request-response.md

Co-authored-by: Shane Myrick &lt;accounts@shanemyrick.com&gt;
Co-authored-by: Dariusz Kuc &lt;dariusz_kuc@hotmail.com&gt;
diff --git a/README.md b/README.md
@@ -5,7 +5,9 @@
 [![codecov](https://codecov.io/gh/ExpediaGroup/graphql-kotlin/branch/master/graph/badge.svg)](https://codecov.io/gh/ExpediaGroup/graphql-kotlin)
 [![Slack](https://img.shields.io/badge/Slack-%23graphql--kotlin-ECB22E.svg?logo=data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgNTQgNTQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGcgZmlsbD0ibm9uZSIgZmlsbC1ydWxlPSJldmVub2RkIj48cGF0aCBkPSJNMTkuNzEyLjEzM2E1LjM4MSA1LjM4MSAwIDAgMC01LjM3NiA1LjM4NyA1LjM4MSA1LjM4MSAwIDAgMCA1LjM3NiA1LjM4Nmg1LjM3NlY1LjUyQTUuMzgxIDUuMzgxIDAgMCAwIDE5LjcxMi4xMzNtMCAxNC4zNjVINS4zNzZBNS4zODEgNS4zODEgMCAwIDAgMCAxOS44ODRhNS4zODEgNS4zODEgMCAwIDAgNS4zNzYgNS4zODdoMTQuMzM2YTUuMzgxIDUuMzgxIDAgMCAwIDUuMzc2LTUuMzg3IDUuMzgxIDUuMzgxIDAgMCAwLTUuMzc2LTUuMzg2IiBmaWxsPSIjMzZDNUYwIi8+PHBhdGggZD0iTTUzLjc2IDE5Ljg4NGE1LjM4MSA1LjM4MSAwIDAgMC01LjM3Ni01LjM4NiA1LjM4MSA1LjM4MSAwIDAgMC01LjM3NiA1LjM4NnY1LjM4N2g1LjM3NmE1LjM4MSA1LjM4MSAwIDAgMCA1LjM3Ni01LjM4N20tMTQuMzM2IDBWNS41MkE1LjM4MSA1LjM4MSAwIDAgMCAzNC4wNDguMTMzYTUuMzgxIDUuMzgxIDAgMCAwLTUuMzc2IDUuMzg3djE0LjM2NGE1LjM4MSA1LjM4MSAwIDAgMCA1LjM3NiA1LjM4NyA1LjM4MSA1LjM4MSAwIDAgMCA1LjM3Ni01LjM4NyIgZmlsbD0iIzJFQjY3RCIvPjxwYXRoIGQ9Ik0zNC4wNDggNTRhNS4zODEgNS4zODEgMCAwIDAgNS4zNzYtNS4zODcgNS4zODEgNS4zODEgMCAwIDAtNS4zNzYtNS4zODZoLTUuMzc2djUuMzg2QTUuMzgxIDUuMzgxIDAgMCAwIDM0LjA0OCA1NG0wLTE0LjM2NWgxNC4zMzZhNS4zODEgNS4zODEgMCAwIDAgNS4zNzYtNS4zODYgNS4zODEgNS4zODEgMCAwIDAtNS4zNzYtNS4zODdIMzQuMDQ4YTUuMzgxIDUuMzgxIDAgMCAwLTUuMzc2IDUuMzg3IDUuMzgxIDUuMzgxIDAgMCAwIDUuMzc2IDUuMzg2IiBmaWxsPSIjRUNCMjJFIi8+PHBhdGggZD0iTTAgMzQuMjQ5YTUuMzgxIDUuMzgxIDAgMCAwIDUuMzc2IDUuMzg2IDUuMzgxIDUuMzgxIDAgMCAwIDUuMzc2LTUuMzg2di01LjM4N0g1LjM3NkE1LjM4MSA1LjM4MSAwIDAgMCAwIDM0LjI1bTE0LjMzNi0uMDAxdjE0LjM2NEE1LjM4MSA1LjM4MSAwIDAgMCAxOS43MTIgNTRhNS4zODEgNS4zODEgMCAwIDAgNS4zNzYtNS4zODdWMzQuMjVhNS4zODEgNS4zODEgMCAwIDAtNS4zNzYtNS4zODcgNS4zODEgNS4zODEgMCAwIDAtNS4zNzYgNS4zODciIGZpbGw9IiNFMDFFNUEiLz48L2c+PC9zdmc+&labelColor=611f69)](https://kotlinlang.slack.com/messages/graphql-kotlin/)
 
-GraphQL Kotlin is a collection of libraries, built on top of [graphql-java](https://www.graphql-java.com/), that aim to simplify running GraphQL in Kotlin
+GraphQL Kotlin is a collection of libraries, built on top of [graphql-java](https://www.graphql-java.com/), that aim to simplify running GraphQL clients and servers in Kotlin.
+
+Visit our [documentation site](https://expediagroup.github.io/graphql-kotlin) for more details.
 
 ## 📦 Modules
 
@@ -15,48 +17,25 @@ GraphQL Kotlin is a collection of libraries, built on top of [graphql-java](http
 * [graphql-kotlin-schema-generator](/graphql-kotlin-schema-generator) - Code only GraphQL schema generation for Kotlin
 * [graphql-kotlin-spring-server](/graphql-kotlin-spring-server) - Spring Boot auto-configuration library to create a GraphQL server
 * [graphql-kotlin-types](/graphql-kotlin-types) - Core types used by both client and server
-* [plugins](/plugins) - GraphQL Kotlin Gradle and Maven plugins
+* [plugins](/plugins) - Gradle and Maven plugins
 
 ## ⌨️ Usage
 
-Below is a basic example of how you can use [graphql-kotlin-spring-server](/graphql-kotlin-spring-server) to run a GraphQL server. For more details, see our documentation below or in the individual module READMEs
-
-```kotlin
-// Simple data class that is parsed by the schema generator
-data class Widget(val id: Int, val value: String)
-
-// Mark the class as a Spring GraphQL Query
-@Component
-class WidgetService : Query {
-  fun widgetById(id: Int): Widget? = null
-}
-
-@SpringBootApplication
-class Application
+While all the individual modules of `graphql-kotlin` are published as stand-alone libraries, the most common use cases are running a server, and genereating a type-safe client.
 
-fun main(args: Array<String>) {
-    runApplication<Application>(*args)
-}
-```
+### Server Example
 
-will generate a server at `/graphql` and `/playground` with the following schema
+A basic example of how you can use [graphql-kotlin-spring-server](/graphql-kotlin-spring-server) to run a GraphQL server can be found on our [server documentation section](https://expediagroup.github.io/graphql-kotlin/docs/spring-server/spring-overview).
 
-```graphql
-type Query {
-  widgetById(id: Int!): Widget
-}
+### Client Example
 
-type Widget {
-  id: Int!
-  value: String!
-}
-```
+A basic setup of [graphql-kotlin-client](/graphql-kotlin-client) can be found on our [client documentation section](https://expediagroup.github.io/graphql-kotlin/docs/client/client-overview).
 
 ## 📋 Documentation
 
-Examples and documentation are available on our [documentation site](https://expediagroup.github.io/graphql-kotlin) hosted in GitHub Pages.
+More examples and documentation are available on our [documentation site](https://expediagroup.github.io/graphql-kotlin) hosted in GitHub Pages. We also have the [examples](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples) module which can be run locally for testing and shows example code using the libraries.
 
-If you have a question about something you can not find in our documentation, the indivdual module READMEs, or [javadocs](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-schema-generator), feel free to [create an issue](https://github.com/ExpediaGroup/graphql-kotlin/issues) and tag it with the question label.
+If you have a question about something you can not find in our documentation, the indivdual module READMEs, or [javadocs](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-schema-generator), feel free to contribute to the docs or [create an issue](https://github.com/ExpediaGroup/graphql-kotlin/issues) and tag it with the question label.
 
 If you would like to contribute to our documentation see the [website](/website) directory for more information.
 
@@ -80,12 +59,12 @@ To get started, please fork the repo and checkout a new branch. You can then bui
 ./gradlew clean build
 ```
 
-
 See more info in [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## 🛡️ Security
 
-For more info on how to contact the team for security issues or the supported versions that recieve security updates, see [SECURITY.md](./.github/SECURITY.md).
+For more info on how to contact the team for security issues or the supported versions that recieve security updates, see [SECURITY.md](./.github/SECURITY.md)
 
 ## ⚖️ License
+
 This library is licensed under the [Apache License, Version 2.0](LICENSE)
diff --git a/docs/federated/apollo-federation.md b/docs/federated/apollo-federation.md
@@ -9,9 +9,80 @@ feasible making it much harder to manage and leading to unnecessary bottlenecks.
 an API gateway and a number of smaller GraphQL services behind it alleviates some of those problems and allows teams to
 scale their graphs more easily.
 
-[Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction/) is an architecture for 
-composing multiple GraphQL services into a single graph. Federated schemas rely on a number of custom directives to 
-instrument the behavior of the underlying graph and convey the relationships between different schema types. Each individual 
-GraphQL server generates a valid GraphQL schema and can be run independently. This is in contrast with traditional schema 
-stitching approach where relationships between individual services, i.e. linking configuration, is configured at the GraphQL 
+[Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction/) is an architecture for
+composing multiple GraphQL services into a single graph. Federated schemas rely on a number of custom directives to
+instrument the behavior of the underlying graph and convey the relationships between different schema types. Each individual
+GraphQL server generates a valid GraphQL schema and can be run independently. This is in contrast with traditional schema
+stitching approach where relationships between individual services, i.e. linking configuration, is configured at the GraphQL
 Gateway level.
+
+## Install
+Using a JVM dependency manager, simply link `graphql-kotlin-federation` to your project.
+
+With Maven:
+
+```xml
+<dependency>
+  <groupId>com.expediagroup</groupId>
+  <artifactId>graphql-kotlin-federation</artifactId>
+  <version>${latestVersion}</version>
+</dependency>
+```
+
+With Gradle:
+
+```kotlin
+implementation("com.expediagroup", "graphql-kotlin-federation", latestVersion)
+```
+
+
+## Usage
+
+`graphql-kotlin-federation` build on top of `graphql-kotlin-schema-generator` and adds a few extra methods and class to use to generate federation
+compliant schemas.
+
+### `toFederatedSchema`
+
+
+Just like the basic [toSchema](../schema-generator/schema-generator-getting-started.md), `toFederatedSchema` accepts four parameters: `config`, `queries`, `mutations` and `subscriptions`.
+The difference is that the `config` class is of type [FederatedSchemaGeneratorConfig](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/federation/FederatedSchemaGeneratorConfig.kt).
+This class extends the [base configuration class](../schema-generator/customizing-schemas/generator-config.md) and adds some default logic. You can override the logic if needed, but do so with caution as you may no longer generate a spec compliant schema.
+
+You can see the definition for `toFederatedSchema` [in the
+source](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/federation/toFederatedSchema.kt)
+
+## Example
+
+```kotlin
+@KeyDirective(fields = FieldSet("id"))
+data class User(
+  val id: ID,
+  val name: String
+)
+
+class Query {
+  fun getUsers(): List<User> = getUsersFromDB()
+}
+
+val config = FederatedSchemaGeneratorConfig(
+  supportedPackages = "com.example"
+)
+
+toFederatedSchema(
+  config = config,
+  queries = listOf(TopLevelObject(Query()))
+)
+```
+
+will generate
+
+ ```graphql
+type Query {
+  getUsers: [User!]!
+}
+
+type User @key(fields : "id") {
+  id: ID!
+  name: String!
+}
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -48,8 +48,8 @@ Repository](https://search.maven.org/artifact/com.expediagroup/graphql-kotlin-sp
 
 ### Gradle
 
-```groovy
-compile(group: 'com.expediagroup', name: 'graphql-kotlin-spring-server', version: "$latestVersion")
+```kotlin
+implementation("com.expediagroup", "graphql-kotlin-spring-server", latestVersion)
 ```
 
 ## Generating a Schema
diff --git a/docs/schema-generator/execution/contextual-data.md b/docs/schema-generator/execution/contextual-data.md
@@ -52,5 +52,8 @@ type Query {
 
 Note that the argument that implements `GraphQLContext` is not reflected in the GraphQL schema.
 
+## Spring Server
+For more details on how to create the context while using `graphql-kotlin-spring-server` see the [spring graphql context page](../../spring-server/spring-graphql-context.md).
+
 ### Customization
 The context is injected into the execution through the `FunctionDataFetcher` class. If you want to customize the logic on how the context is determined, that is possible to override. See more details on the [Fetching Data documentation](./fetching-data)
diff --git a/docs/schema-generator/schema-generator-getting-started.md b/docs/schema-generator/schema-generator-getting-started.md
@@ -3,6 +3,27 @@ id: schema-generator-getting-started
 title: Getting Started with the Schema Generator
 ---
 
+## Install
+Using a JVM dependency manager, simply link `graphql-kotlin-schema-generator` to your project.
+
+With Maven:
+
+```xml
+<dependency>
+  <groupId>com.expediagroup</groupId>
+  <artifactId>graphql-kotlin-schema-generator</artifactId>
+  <version>${latestVersion}</version>
+</dependency>
+```
+
+With Gradle:
+
+```kotlin
+implementation("com.expediagroup", "graphql-kotlin-schema-generator", latestVersion)
+```
+
+## Usage
+
 `graphql-kotlin-schema-generator` provides a single function, `toSchema`, to generate a schema from Kotlin objects.
 
 ```kotlin
diff --git a/docs/spring-server/http-request-response.md b/docs/spring-server/http-request-response.md
@@ -0,0 +1,12 @@
+---
+id: http-request-response
+title: Access the HTTP Request-Response
+---
+
+GraphQL is strongly typed and any data that is not part of the schema is no longer automatically known by the clients. Relying on this information becomes an "undocumented" part of your API. As a result, by default, GraphQL query resolvers do not have access to the raw HTTP request and response objects.
+
+That being said, there are some common use cases (like authorization) that require inspecting HTTP headers.
+
+## GraphQL Context
+
+The most common way to access the raw HTTP request and response objects is to process them when creating the GraphQLContext through the Spring bean [GraphQLContextFactory](./spring-graphql-context.md). Using the factory you can then extract the information from the incoming request and store it in the context so it can be accessed from any resolver.
diff --git a/docs/spring-server/spring-overview.md b/docs/spring-server/spring-overview.md
@@ -7,7 +7,11 @@ title: Spring Server Overview
 is a Spring Boot auto-configuration library that automatically configures beans required to start up a reactive GraphQL
 web server.
 
-This library is built on a [Spring WebFlux (reactive)](https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html) stack which is a non-blocking alternative to a traditional [Spring Web MVC (servlet)](https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html) based stack. Since both frameworks utilize different threading models they cannot and should not be intermixed. When building a GraphQL server using `graphql-kotlin-spring-server` all your queries and mutations should follow one of the supported [asynchronous execution models](https://expediagroup.github.io/graphql-kotlin/docs/execution/async-models).
+## WebFlux vs WebMVC
+
+This library is built on a [Spring WebFlux (reactive)](https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html) stack which is a non-blocking alternative to a traditional [Spring Web MVC (servlet)](https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html) based stack.
+Since both frameworks utilize different threading models they cannot and should not be intermixed.
+When building a GraphQL server using `graphql-kotlin-spring-server` all your queries and mutations should follow one of the supported [asynchronous execution models](https://expediagroup.github.io/graphql-kotlin/docs/execution/async-models).
 
 ## Setup
 
@@ -29,8 +33,8 @@ With Maven:
 
 With Gradle:
 
-```groovy
-compile(group: 'com.expediagroup', name: 'graphql-kotlin-spring-server', version: "$latestVersion")
+```kotlin
+implementation("com.expediagroup", "graphql-kotlin-spring-server", latestVersion)
 ```
 
 ## Configuration
@@ -104,4 +108,4 @@ Your newly created GraphQL server starts up with following preconfigured default
 * **/graphql** - GraphQL server endpoint used for processing queries and mutations
 * **/subscriptions** - GraphQL server endpoint used for processing subscriptions
 * **/sdl** - Convenience endpoint that returns current schema in Schema Definition Language format
-* **/playground** - Prisma Labs GraphQL Playground IDE endpoint
+* **/playground** - Prisma Labs [GraphQL Playground IDE](https://github.com/prisma-labs/graphql-playground) endpoint
diff --git a/graphql-kotlin-federation/README.md b/graphql-kotlin-federation/README.md
@@ -29,8 +29,8 @@ With Maven:
 
 With Gradle:
 
-```groovy
-compile(group: 'com.expediagroup', name: 'graphql-kotlin-federation', version: "$latestVersion")
+```kotlin
+implementation("com.expediagroup", "graphql-kotlin-federation", latestVersion)
 ```
 
 ## Usage
diff --git a/graphql-kotlin-schema-generator/README.md b/graphql-kotlin-schema-generator/README.md
@@ -24,8 +24,8 @@ With Maven:
 
 With Gradle:
 
-```groovy
-compile(group: 'com.expediagroup', name: 'graphql-kotlin-schema-generator', version: "$latestVersion")
+```kotlin
+implementation("com.expediagroup", "graphql-kotlin-schema-generator", latestVersion)
 ```
 
 ## Usage
@@ -40,7 +40,7 @@ class WidgetService {
   fun widgetById(id: Int): Widget? {
     // grabs widget from a data source, might return null
   }
-  
+
   @Deprecated("Use widgetById")
   fun widgetByValue(value: String): Widget? {
     // grabs widget from a deprecated data source, might return null
@@ -72,7 +72,7 @@ schema {
 
 type Query {
   widgetById(id: Int!): Widget
-  
+
   widgetByValue(vale: String!): Widget @deprecated(reason: "Use widgetById")
 }
 
diff --git a/graphql-kotlin-spring-server/README.md b/graphql-kotlin-spring-server/README.md
@@ -2,7 +2,7 @@
 [![Maven Central](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-spring-server.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.expediagroup%22%20AND%20a:%22graphql-kotlin-spring-server%22)
 [![Javadocs](https://img.shields.io/maven-central/v/com.expediagroup/graphql-kotlin-spring-server.svg?label=javadoc&colorB=brightgreen)](https://www.javadoc.io/doc/com.expediagroup/graphql-kotlin-spring-server)
 
-`graphql-kotlin-spring-server` is a Spring Boot autoconfiguration library that automatically configures beans required to start up reactive GraphQL web server. 
+`graphql-kotlin-spring-server` is a Spring Boot autoconfiguration library that automatically configures beans required to start up reactive GraphQL web server.
 
 
 ## Installation
@@ -21,8 +21,8 @@ With Maven:
 
 With Gradle:
 
-```groovy
-compile(group: 'com.expediagroup', name: 'graphql-kotlin-spring-server', version: "$latestVersion")
+```kotlin
+implementation("com.expediagroup", "graphql-kotlin-spring-server", latestVersion)
 ```
 
 ## Usage
@@ -31,15 +31,15 @@ At a minimum, in order for `graphql-kotlin-spring-server` to automatically confi
 
 ```yaml
 graphql:
-  packages: 
+  packages:
     - "com.your.package"
 ```
 
 In order to expose your queries, mutations and subscriptions in the GraphQL schema you simply need to implement corresponding marker interfaces and they will be automatically picked up by `graphql-kotlin-spring-server` autoconfiguration library.
 
 ```kotlin
 @Component
-class MyAwesomeQuery : Query { 
+class MyAwesomeQuery : Query {
   fun myAwesomeQuery(): Widget { ... }
 }
 
diff --git a/website/sidebars.json b/website/sidebars.json
@@ -60,6 +60,7 @@
       "spring-server/spring-beans",
       "spring-server/spring-properties",
       "spring-server/spring-graphql-context",
+      "spring-server/http-request-response",
       "spring-server/subscriptions"
     ],
     "HTTP Client": [
