From 1ff688624e6cb962b67b3e546b9d17197c97ca36 Mon Sep 17 00:00:00 2001 From: Dariusz Kuc <9501705+dariuszkuc@users.noreply.github.com> Date: Sat, 6 May 2023 19:17:16 -0500 Subject: [PATCH] docs: cleanup tasks/mojos usage documentation (#1766) --- .../plugins/gradle-plugin-usage-client.mdx | 3 + .../docs/plugins/gradle-plugin-usage-sdl.mdx | 8 ++- .../docs/plugins/maven-plugin-usage-client.md | 71 +------------------ .../docs/plugins/maven-plugin-usage-sdl.md | 8 ++- 4 files changed, 18 insertions(+), 72 deletions(-) diff --git a/website/docs/plugins/gradle-plugin-usage-client.mdx b/website/docs/plugins/gradle-plugin-usage-client.mdx index 94fe8cf7c6..8e33db432e 100644 --- a/website/docs/plugins/gradle-plugin-usage-client.mdx +++ b/website/docs/plugins/gradle-plugin-usage-client.mdx @@ -7,6 +7,9 @@ sidebar_label: Generating Client import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +GraphQL Kotlin plugins can be used to generate a lightweight type-safe GraphQL HTTP clients. See examples below for more +information about the client generating tasks. + ## Downloading Schema SDL GraphQL endpoints are often public and as such many servers might disable introspection queries in production environment. diff --git a/website/docs/plugins/gradle-plugin-usage-sdl.mdx b/website/docs/plugins/gradle-plugin-usage-sdl.mdx index d577940f8e..55b99ca166 100644 --- a/website/docs/plugins/gradle-plugin-usage-sdl.mdx +++ b/website/docs/plugins/gradle-plugin-usage-sdl.mdx @@ -7,7 +7,11 @@ sidebar_label: Generating SDL import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -## Generating SDL Example +GraphQL Kotlin follows a code-first approach where schema is auto generated from your source code at runtime. GraphQL Kotlin +plugins can be used to generate schema as a build time artifact. This allows you to seamlessly integrate with various +GraphQL tools that may require a schema artifact as an input (e.g. to perform backwards compatibility checks, etc). + +## Generating SDL GraphQL schema can be generated directly from your source code using reflections. `graphqlGenerateSDL` will scan your classpath looking for classes implementing `Query`, `Mutation` and `Subscription` marker interfaces and then generates the @@ -76,7 +80,7 @@ This task does not automatically configure itself to be part of your build lifec invoke it OR configure it as a dependency of some other task. ::: -## Generating SDL with Custom Hooks Provider Example +## Using Custom Hooks Provider Plugin will default to use `NoopSchemaGeneratorHooks` to generate target GraphQL schema. If your project uses custom hooks or needs to generate the federated GraphQL schema, you will need to provide an instance of `SchemaGeneratorHooksProvider` diff --git a/website/docs/plugins/maven-plugin-usage-client.md b/website/docs/plugins/maven-plugin-usage-client.md index 4a028177ef..d91a209ba1 100644 --- a/website/docs/plugins/maven-plugin-usage-client.md +++ b/website/docs/plugins/maven-plugin-usage-client.md @@ -4,6 +4,9 @@ title: Maven Plugin Client Usage sidebar_label: Generating Client --- +GraphQL Kotlin plugins can be used to generate a lightweight type-safe GraphQL HTTP clients. See examples below for more +information about the client generating tasks. + ## Downloading Schema SDL Download SDL Mojo requires target GraphQL server `endpoint` to be specified. Task can be executed directly from the @@ -451,71 +454,3 @@ different endpoints. ``` - -## Generating SDL Example - -GraphQL schema can be generated directly from your source code using reflections. `generate-sdl` mojo will scan your -classpath looking for classes implementing `Query`, `Mutation` and `Subscription` marker interfaces and then generates the -corresponding GraphQL schema using `graphql-kotlin-schema-generator` and default `NoopSchemaGeneratorHooks`. In order to -limit the amount of packages to scan, this mojo requires users to provide a list of `packages` that can contain GraphQL -types. - -```xml - - com.expediagroup - graphql-kotlin-maven-plugin - ${graphql-kotlin.version} - - - - generate-sdl - - - - com.example - - - - - -``` - -## Generating SDL with Custom Hooks Provider Example - -Plugin will default to use `NoopSchemaGeneratorHooks` to generate target GraphQL schema. If your project uses custom hooks -or needs to generate the federated GraphQL schema, you will need to provide an instance of `SchemaGeneratorHooksProvider` -service provider that will be used to create an instance of your custom hooks. - -`generate-sdl` mojo utilizes [ServiceLoader](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/ServiceLoader.html) -mechanism to dynamically load available `SchemaGeneratorHooksProvider` service providers from the classpath. Service provider -can be provided as part of your project, included in one of your project dependencies or through explicitly provided artifact. -See [Schema Generator Hooks Provider](./hooks-provider.mdx) for additional details on how to create custom hooks service provider. -Configuration below shows how to configure GraphQL Kotlin plugin with explicitly provided artifact to generate federated -GraphQL schema. - -```xml - - com.expediagroup - graphql-kotlin-maven-plugin - ${graphql-kotlin.version} - - - - generate-sdl - - - - com.example - - - - - - - com.expediagroup - graphql-kotlin-federated-hooks-provider - ${graphql-kotlin.version} - - - -``` diff --git a/website/docs/plugins/maven-plugin-usage-sdl.md b/website/docs/plugins/maven-plugin-usage-sdl.md index 1f87fe557f..32eeb1fdef 100644 --- a/website/docs/plugins/maven-plugin-usage-sdl.md +++ b/website/docs/plugins/maven-plugin-usage-sdl.md @@ -4,7 +4,11 @@ title: Maven Plugin SDL Usage sidebar_label: Generating SDL --- -## Generating SDL Example +GraphQL Kotlin follows a code-first approach where schema is auto generated from your source code at runtime. GraphQL Kotlin +plugins can be used to generate schema as a build time artifact. This allows you to seamlessly integrate with various +GraphQL tools that may require a schema artifact as an input (e.g. to perform backwards compatibility checks, etc). + +## Generating SDL GraphQL schema can be generated directly from your source code using reflections. `generate-sdl` mojo will scan your classpath looking for classes implementing `Query`, `Mutation` and `Subscription` marker interfaces and then generates the @@ -32,7 +36,7 @@ types. ``` -## Generating SDL with Custom Hooks Provider Example +## Using Custom Hooks Provider Plugin will default to use `NoopSchemaGeneratorHooks` to generate target GraphQL schema. If your project uses custom hooks or needs to generate the federated GraphQL schema, you will need to provide an instance of `SchemaGeneratorHooksProvider`