diff --git a/spring-graphql-docs/build.gradle b/spring-graphql-docs/build.gradle index a658984a..3d7db6f5 100644 --- a/spring-graphql-docs/build.gradle +++ b/spring-graphql-docs/build.gradle @@ -1,4 +1,5 @@ plugins { + id 'java' id 'org.asciidoctor.jvm.convert' version '3.3.2' } @@ -8,6 +9,18 @@ configurations { asciidoctorExtensions } +jar { + enabled = false +} + +javadoc { + enabled = false +} + +dependencies { + asciidoctorExtensions 'io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.2' +} + repositories { maven { url "https://repo.spring.io/release" @@ -17,13 +30,10 @@ repositories { } } -dependencies { - asciidoctorExtensions 'io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.2' -} - ext.javadocLinks = [ "https://docs.oracle.com/javase/8/docs/api/", - "https://javadoc.io/doc/com.graphql-java/graphql-java/16.2/", + "https://javadoc.io/doc/com.graphql-java/graphql-java/${graphQlJavaVersion}/", + "https://docs.spring.io/spring-boot/docs/${bootVersion}/api/", "https://docs.spring.io/spring-framework/docs/5.3.x/javadoc-api/" ] as String[] @@ -82,6 +92,8 @@ asciidoctor { backends "spring-html" } outputDir "$buildDir/docs/reference/html" + attributes 'spring-graphql-version': project.version, + 'spring-boot-version': bootVersion } /** diff --git a/spring-graphql-docs/src/docs/asciidoc/attributes.adoc b/spring-graphql-docs/src/docs/asciidoc/attributes.adoc new file mode 100644 index 00000000..2cd93f1b --- /dev/null +++ b/spring-graphql-docs/src/docs/asciidoc/attributes.adoc @@ -0,0 +1,20 @@ +:!version-label: +:doctype: book +:idprefix: +:idseparator: - +:toc: left +:toclevels: 4 +:tabsize: 4 +:numbered: +:sectanchors: +:sectnums: +:hide-uri-scheme: +:docinfo: shared,private +:github-tag: main +:github-repo: spring-projects/spring-graphql +:github-raw: https://raw.githubusercontent.com/{github-repo}/{github-tag} +:github-issues: https://github.com/{github-repo}/issues/ +:github-main-branch: https://github.com/{github-repo}/tree/main +:github-wiki: https://github.com/{github-repo}/wiki +:spring-boot-version: current +:spring-boot-ref-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/reference/html \ No newline at end of file diff --git a/spring-graphql-docs/src/docs/asciidoc/boot-starter.adoc b/spring-graphql-docs/src/docs/asciidoc/boot-starter.adoc index 46d75a2d..aa00db35 100644 --- a/spring-graphql-docs/src/docs/asciidoc/boot-starter.adoc +++ b/spring-graphql-docs/src/docs/asciidoc/boot-starter.adoc @@ -31,12 +31,12 @@ GraphQL transports you want to use: In the generated project, add `graphql-spring-boot-starter` manually: -[source,groovy,indent=0,subs="verbatim,quotes",role="primary"] +[source,groovy,indent=0,subs="verbatim,quotes,attributes",role="primary"] .Gradle ---- dependencies { // Spring GraphQL Boot starter - implementation 'org.springframework.experimental:graphql-spring-boot-starter:1.0.0-SNAPSHOT' + implementation 'org.springframework.experimental:graphql-spring-boot-starter:{spring-graphql-version}' // ... } @@ -47,7 +47,7 @@ repositories { maven { url 'https://repo.spring.io/snapshot' } // Spring snapshots } ---- -[source,xml,indent=0,subs="verbatim,quotes",role="secondary"] +[source,xml,indent=0,subs="verbatim,quotes,attributes",role="secondary"] .Maven ---- @@ -56,7 +56,7 @@ repositories { org.springframework.experimental graphql-spring-boot-starter - 1.0.0-SNAPSHOT + {spring-graphql-version} @@ -119,10 +119,10 @@ spring.graphql.schema.printer.enabled=false The GraphQL Java `RuntimeWiring.Builder` can be used to register ``DataFetcher``s, type resolvers, custom scalar types, and more. You can declare `RuntimeWiringConfigurer` beans in your Spring config to get access to the `RuntimeWiring.Builder`. The Boot -starter detects such beans adds them to <>. +starter detects such beans adds them to <>. Typically, however, applications will not implement ``DataFetcher`` directly and will -instead create <>. The Boot +instead create <>. The Boot starter declares a `RuntimeWiringConfigurer` called `AnnotatedDataFetcherConfigurer` that detects `@Controller` classes with annotated handler methods and registers those as ``DataFetcher``s. @@ -165,7 +165,7 @@ The GraphQL WebSocket endpoint is off by default. To enable it: - For a WebFlux application, set the `spring.graphql.websocket.path` application property. Declare a `WebInterceptor` bean to have it registered in the -<> for GraphQL over HTTP and WebSocket +<> for GraphQL over HTTP and WebSocket requests. Declare a `ThreadLocalAccessor` bean to assist with the propagation of `ThreadLocal` @@ -179,7 +179,7 @@ values of interest in <>. Spring GraphQL enables applications to register one or more Spring `DataFetcherExceptionResolver` components that are invoked sequentially until one resolves the Exception to a list of `graphql.GraphQLError` objects. See -<> for details. +<> for details. The Boot starter detects beans of type `DataFetcherExceptionResolver` and registers them automatically with the `GraphQlSource.Builder`. @@ -189,7 +189,7 @@ automatically with the `GraphQlSource.Builder`. [[boot-graphql-batch-loader-registry]] == BatchLoaderRegistry -Spring GraphQL supports the GraphQL Java <> and provides +Spring GraphQL supports the GraphQL Java <> and provides a `BatchLoaderRegistry` to store registrations of batch loading functions. The Boot starter declares a `BatchLoaderRegistry` bean and configures the `ExecutionGraphQlService` with it so that applications can simply autowire the registry into their controllers and @@ -313,12 +313,12 @@ A GraphQL error metric counter is available at `/actuator/metrics/graphql.error` For Spring GraphQL testing support, add the below to your classpath and that will make a `WebGraphQlTester` available for injection into tests: -[source,groovy,indent=0,subs="verbatim,quotes",role="primary"] +[source,groovy,indent=0,subs="verbatim,quotes,attributes",role="primary"] .Gradle ---- dependencies { testImplementation 'org.springframework.boot:spring-boot-starter-test' - testImplementation 'org.springframework.graphql:spring-graphql-test:1.0.0-SNAPSHOT' + testImplementation 'org.springframework.graphql:spring-graphql-test:{spring-graphql-version}' // Also add this, unless `spring-boot-starter-webflux` is also present testImplementation 'org.springframework:spring-webflux' @@ -332,7 +332,7 @@ repositories { maven { url 'https://repo.spring.io/snapshot' } // Spring snapshots } ---- -[source,xml,indent=0,subs="verbatim,quotes",role="secondary"] +[source,xml,indent=0,subs="verbatim,quotes,attributes",role="secondary"] .Maven ---- @@ -345,7 +345,7 @@ repositories { org.springframework.graphql spring-graphql-test - 1.0.0-SNAPSHOT + {spring-graphql-version} test @@ -394,7 +394,7 @@ public class MockMvcGraphQlTests { ---- For GraphQL over HTTP with Spring WebFlux, using a -https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.testing.spring-boot-applications.with-mock-environment[mock server]: +{spring-boot-ref-docs}/features.html#features.testing.spring-boot-applications.with-mock-environment[mock server]: [source,java,indent=0,subs="verbatim,quotes"] ---- @@ -410,7 +410,7 @@ public class MockMvcGraphQlTests { ---- For GraphQL over HTTP with a -https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.testing.spring-boot-applications.with-running-server[running server]: +{spring-boot-ref-docs}/features.html#features.testing.spring-boot-applications.with-running-server[running server]: [source,java,indent=0,subs="verbatim,quotes"] ---- diff --git a/spring-graphql-docs/src/docs/asciidoc/index.adoc b/spring-graphql-docs/src/docs/asciidoc/index.adoc index 9217abc2..e59374dd 100644 --- a/spring-graphql-docs/src/docs/asciidoc/index.adoc +++ b/spring-graphql-docs/src/docs/asciidoc/index.adoc @@ -1,11 +1,6 @@ = Spring GraphQL Documentation Brian Clozel; Andreas Marek; Rossen Stoyanchev -:toc: left -:toclevels: 4 -:tabsize: 4 - -:repository: https://github.com/spring-projects/spring-graphql/tree/main - +include::attributes.adoc[] [[overview]] @@ -58,7 +53,7 @@ Boot starter does this, see <> for details or check `GraphQlWebMvcAutoConfiguration` or `GraphQlWebFluxAutoConfiguration` for example config. The Spring GraphQL repository contains a Spring MVC -{repository}/samples/webmvc-http[HTTP sample] application. +{github-main-branch}/samples/webmvc-http[HTTP sample] application. @@ -99,7 +94,7 @@ starter has options to enable this, see <> for details or chec `GraphQlWebMvcAutoConfiguration` or `GraphQlWebFluxAutoConfiguration` for example config. The Spring GraphQL repository contains a WebFlux -{repository}/samples/webflux-websocket[WebSocket sample] application. +{github-main-branch}/samples/webflux-websocket[WebSocket sample] application. @@ -372,7 +367,7 @@ If the repository is `ReactiveQuerydslPredicateExecutor`, the builder returns `DataFetcher>` or `DataFetcher>`. Spring Data supports this variant for MongoDB. -The {repository}/samples/webmvc-http[webmvc-http] sample in the Spring GraphQL repository +The {github-main-branch}/samples/webmvc-http[webmvc-http] sample in the Spring GraphQL repository uses Querydsl to fetch `artifactRepositories`. @@ -701,8 +696,8 @@ the GraphQL response. This should work due to <> that aims to Security, and other context, available at the data fetching level. The Spring GraphQL repository contains samples for -{repository}/samples/webmvc-http-security[Spring MVC] and for -{repository}/samples/webflux-security[WebFlux]. +{github-main-branch}/samples/webmvc-http-security[Spring MVC] and for +{github-main-branch}/samples/webflux-security[WebFlux]. @@ -720,7 +715,7 @@ include::boot-starter.adoc[leveloffset=+1] [[samples]] == Samples -This Spring GraphQL repository contains {repository}/samples[sample applications] for +This Spring GraphQL repository contains {github-main-branch}/samples[sample applications] for various scenarios. You can run those by cloning this repository and running main application classes from diff --git a/spring-graphql-docs/src/docs/asciidoc/testing.adoc b/spring-graphql-docs/src/docs/asciidoc/testing.adoc index cca7a60b..b2e5c90f 100644 --- a/spring-graphql-docs/src/docs/asciidoc/testing.adoc +++ b/spring-graphql-docs/src/docs/asciidoc/testing.adoc @@ -38,12 +38,12 @@ To create `GraphQlTester`, you only need a `GraphQlService`, and no transport: == `WebGraphQlTester` `WebGraphQlTester` extends `GraphQlTester` to add a workflow and configuration specific -to <>. You need one of the following inputs to create it: +to <>. You need one of the following inputs to create it: -- `WebTestClient` -- perform requests as an HTTP client, either against <> +- `WebTestClient` -- perform requests as an HTTP client, either against <> handlers without a server, or against a live server. -- `WebGraphQlHandler` -- perform requests through the <> chain used -by both <> and <> handlers, which in effect is testing without +- `WebGraphQlHandler` -- perform requests through the <> chain used +by both <> and <> handlers, which in effect is testing without a Web framework. One reason to use this is for <>. For Spring WebFlux without a server, you can point to your Spring configuration: @@ -202,7 +202,7 @@ The `StepVerifier` from Project Reactor is useful to verify a stream: .verifyComplete(); ---- -To test with the <> chain, you can create `WebGraphQlTester` with a +To test with the <> chain, you can create `WebGraphQlTester` with a `WebGraphQlHandler`: [source,java,indent=0,subs="verbatim,quotes"]