diff --git a/docs/assets/spring-initializer.png b/docs/assets/spring-initializer.png new file mode 100644 index 0000000000..0f4eaca9a8 Binary files /dev/null and b/docs/assets/spring-initializer.png differ diff --git a/docs/blogs-and-videos.md b/docs/blogs-and-videos.md index 9788586f53..a01167a198 100644 --- a/docs/blogs-and-videos.md +++ b/docs/blogs-and-videos.md @@ -8,15 +8,19 @@ Here are some links to other blog posts and videos which may provide further exa ### From the Expedia Group team #### graphql-kotlin +Articles and videos specifically about `graphql-kotlin` + * 📝 [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) * 📝 [Release of graphql-kotlin 1.0.0!](https://medium.com/expedia-group-tech/release-of-graphql-kotlin-1-0-0-791ad85d3116) * 📝 [Creating GraphQL Schemas in Kotlin](https://medium.com/expedia-group-tech/creating-graphql-schemas-in-kotlin-aaaac0ab0672) -* 📝[Apollo Federation in a GraphQL Kotlin Server](https://medium.com/expedia-group-tech/apollo-federation-in-a-graphql-kotlin-server-115cea51607a) -* 📝[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) +* 📝 [Apollo Federation in a GraphQL Kotlin Server](https://medium.com/expedia-group-tech/apollo-federation-in-a-graphql-kotlin-server-115cea51607a) +* 📝 [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) +* 📺 [Bootiful GraphQL with Kotlin (Dariusz Kuc, Guillaume Scheibel)](https://www.youtube.com/watch?v=7YJyPXjLdug&index=25) (en) #### GraphQL +Articles and videos about how Expedia Group is using GraphQL + * 📺 [Creating a federated schema for a global company (Shane Myrick)](https://youtu.be/MuD3TAP0D9Y) (en) * 📺 [Migrer ses APIs vers GraphQL: pourquoi? comment! (Guillaume Scheibel)](https://youtu.be/IRIkpvJo95s) (fr) * 📺 [Migrate your APIs to GraphQL: how? and why! (Guillaume Scheibel)](https://youtu.be/IkPMpzQ-TRI) (en) * 📺 [Transforming customer experiences and your organization with GraphQL (Jim Gust, Dan Boerner)](https://youtu.be/Jt-ZD4zj4Ow) (en) -* 📺 [Bootiful GraphQL with Kotlin (Dariusz Kuc, Guillaume Scheibel)](https://www.youtube.com/watch?v=7YJyPXjLdug&index=25) (en) diff --git a/docs/examples.md b/docs/examples.md index 217bb7bff9..4940eb4681 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,24 +1,24 @@ ---- -id: examples -title: Examples ---- - -## Spring Example - -One way to run a GraphQL server is with [Spring Boot](https://github.com/spring-projects/spring-boot). A sample Spring -Boot app that uses [Spring -Webflux](https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html) together with -`graphql-kotlin-schema-generator` and [graphql-playground](https://github.com/prisma/graphql-playground) is provided as -a [examples/spring](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/spring). All the examples used -in this documentation should be available in the sample app. - -In order to run it you can run -[Application.kt](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/Application.kt) -directly from your IDE. Alternatively you can also use the Spring Boot maven plugin by running `mvn spring-boot:run` -from the command line. Once the app has started you can explore the example schema by opening Playground endpoint at -[http://localhost:8080/playground](http://localhost:8080/playground). - -## Federation Example - -There is also an example of [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction/) with two Spring Boot apps using `graphql-kotlin-federation` and an Apollo Gateway app in Nodejs that exposes a single federated schema in [examples/federation](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/federation) -project. Please refer to the README files for details on how to run each application. +--- +id: examples +title: Examples +--- + +## Spring Server Example + +One way to run a GraphQL server is with [Spring Boot](https://github.com/spring-projects/spring-boot). A sample Spring +Boot app that uses [Spring +Webflux](https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html) together with +`graphql-kotlin-schema-generator` and [graphql-playground](https://github.com/prisma/graphql-playground) is provided as +a [examples/spring](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/spring). All the examples used +in this documentation should be available in the sample app. + +In order to run it you can run +[Application.kt](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/examples/spring/src/main/kotlin/com/expediagroup/graphql/examples/Application.kt) +directly from your IDE. Alternatively you can also use the Spring Boot maven plugin by running `mvn spring-boot:run` +from the command line. Once the app has started you can explore the example schema by opening Playground endpoint at +[http://localhost:8080/playground](http://localhost:8080/playground). + +## Federation Example + +There is also an example of [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction/) with two Spring Boot apps using `graphql-kotlin-federation` and an Apollo Gateway app in Nodejs that exposes a single federated schema in [examples/federation](https://github.com/ExpediaGroup/graphql-kotlin/tree/master/examples/federation) +project. Please refer to the README files for details on how to run each application. diff --git a/docs/getting-started.md b/docs/getting-started.md index af814c6a0b..e8bb5aa120 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,5 +1,5 @@ --- -id: getting-started +id: getting-started title: Getting Started --- @@ -79,7 +79,7 @@ The `GraphQLSchema` generated can be used to expose a GraphQL API endpoint. This function accepts four arguments: `config`, `queries`, `mutations` and `subscriptions`. The `queries`, `mutations` and `subscriptions` are a list of `TopLevelObject`s and will be used to generate corresponding GraphQL root types. See below on why we use this wrapper class. The `config` contains all the extra information you need to pass, including -custom hooks, supported packages, and name overrides. See the full documentation: [Spring Server Overview](server/spring-overview). +custom hooks, supported packages, and name overrides. See the full documentation: [Spring Server Overview](spring-server/spring-overview). You can see the definition for `toSchema` [in the source](https://github.com/ExpediaGroup/graphql-kotlin/blob/master/graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/toSchema.kt) diff --git a/docs/server/spring-beans.md b/docs/spring-server/spring-beans.md similarity index 100% rename from docs/server/spring-beans.md rename to docs/spring-server/spring-beans.md diff --git a/docs/server/spring-graphql-context.md b/docs/spring-server/spring-graphql-context.md similarity index 100% rename from docs/server/spring-graphql-context.md rename to docs/spring-server/spring-graphql-context.md diff --git a/docs/server/spring-overview.md b/docs/spring-server/spring-overview.md similarity index 60% rename from docs/server/spring-overview.md rename to docs/spring-server/spring-overview.md index 14fc4dff18..9939ae8f7b 100644 --- a/docs/server/spring-overview.md +++ b/docs/spring-server/spring-overview.md @@ -7,6 +7,36 @@ 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). + +## Setup + +### Creating a Spring Server + +The simplest way to create a new Kotlin Spring Boot app is by generating one using [Spring Initializr.](https://start.spring.io/) + +![Image of https://start.spring.io/](assets/spring-initializer.png) + +Once you get the sample application setup locally, you will need to add `graphql-kotlin-spring-server` dependency: + +With Maven: + +```xml + + com.expediagroup + graphql-kotlin-spring-server + ${latestVersion} + +``` + +With Gradle: + +```groovy +compile(group: 'com.expediagroup', name: 'graphql-kotlin-spring-server', version: "$latestVersion") +``` + +### Configuration + At a minimum, in order for `graphql-kotlin-spring-server` to automatically configure your GraphQL web server you need to specify a list of supported packages that can be scanned for exposing your schema objects through reflections. @@ -18,7 +48,7 @@ graphql: - "com.your.package" ``` - +### Writing Schema Code In order to expose your queries, mutations and/or subscriptions in the GraphQL schema you simply need to implement corresponding marker interface and they will be automatically picked up by `graphql-kotlin-spring-server` auto-configuration library. @@ -69,6 +99,8 @@ type Widget { } ``` +### Default Routes + Your newly created GraphQL server starts up with following preconfigured default routes: * **/graphql** - GraphQL server endpoint used for processing queries and mutations diff --git a/docs/server/spring-properties.md b/docs/spring-server/spring-properties.md similarity index 100% rename from docs/server/spring-properties.md rename to docs/spring-server/spring-properties.md diff --git a/docs/server/subscriptions.md b/docs/spring-server/subscriptions.md similarity index 100% rename from docs/server/subscriptions.md rename to docs/spring-server/subscriptions.md diff --git a/website/sidebars.json b/website/sidebars.json index 653154ce0a..3fd83d6926 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -51,11 +51,11 @@ "federated/type-resolution" ], "Spring Server": [ - "server/spring-overview", - "server/spring-beans", - "server/spring-properties", - "server/spring-graphql-context", - "server/subscriptions" + "spring-server/spring-overview", + "spring-server/spring-beans", + "spring-server/spring-properties", + "spring-server/spring-graphql-context", + "spring-server/subscriptions" ], "Contributors": [ "contributors/release-proc"