This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch CAUSEWAY-3676
in repository https://gitbox.apache.org/repos/asf/causeway.git
The following commit(s) were added to refs/heads/CAUSEWAY-3676 by this push:
new 7a96ff4d16 CAUSEWAY-3676: wip on antora docs for GraphQL, also renames
the modules (remove 'Inc', leftover from incubation)
7a96ff4d16 is described below
commit 7a96ff4d1693c682778de90d173c3921cd2a583b
Author: danhaywood <[email protected]>
AuthorDate: Sun Jan 28 13:10:20 2024 +0000
CAUSEWAY-3676: wip on antora docs for GraphQL, also renames the modules
(remove 'Inc', leftover from incubation)
---
.../components/docs/modules/ROOT/pages/about.adoc | 1 +
.../ROOT/partials/module-nav/components.adoc | 1 +
.../devnotes/example-demo-app-included-modules.png | Bin
.../images/devnotes/graphql-included-modules.png | Bin
.../adoc/modules/{graphql => ROOT}/nav.adoc | 0
.../modules/{graphql => ROOT}/pages/about.adoc | 11 ++-
.../ROOT/pages/setup-and-configuration.adoc | 54 ++++++++++++
.../adoc/modules/ROOT/partials/component-nav.adoc | 5 ++
.../adoc/modules/ROOT/partials/module-nav.adoc | 3 +
.../adoc/modules/graphql/pages/devnotes.adoc | 96 ---------------------
.../adoc/modules/graphql/partials/module-nav.adoc | 4 -
...java => CausewayModuleViewerGraphqlApplib.java} | 2 +-
....java => CausewayModuleViewerGraphqlModel.java} | 6 +-
...ayViewerGraphqlTestModuleIntegTestAbstract.java | 4 +-
...java => CausewayModuleViewerGraphqlViewer.java} | 13 +--
.../adoc/modules/ROOT/pages/about.adoc | 5 ++
16 files changed, 85 insertions(+), 120 deletions(-)
diff --git a/antora/components/docs/modules/ROOT/pages/about.adoc
b/antora/components/docs/modules/ROOT/pages/about.adoc
index 3c823e4456..6321a93248 100644
--- a/antora/components/docs/modules/ROOT/pages/about.adoc
+++ b/antora/components/docs/modules/ROOT/pages/about.adoc
@@ -83,6 +83,7 @@ _Security_
_Viewers_
* xref:vw:ROOT:about.adoc[Web UI (Wicket)]
+* xref:gqlv:ROOT:about.adoc[GraphQL API]
* xref:vro:ROOT:about.adoc[REST API (Restful{nbsp}Objects)]
_Persistence_
diff --git
a/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
b/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
index b4e521a8e5..e0fa53efb8 100644
--- a/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
+++ b/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
@@ -13,6 +13,7 @@
** Viewers
*** xref:vw:ROOT:about.adoc[Web UI (Wicket)]
+*** xref:gqlv:ROOT:about.adoc[GraphQL API]
*** xref:vro:ROOT:about.adoc[REST API (Restful Objects)]
** Persistence
diff --git
a/viewers/graphql/adoc/modules/graphql/images/devnotes/example-demo-app-included-modules.png
b/viewers/graphql/adoc/modules/ROOT/images/devnotes/example-demo-app-included-modules.png
similarity index 100%
rename from
viewers/graphql/adoc/modules/graphql/images/devnotes/example-demo-app-included-modules.png
rename to
viewers/graphql/adoc/modules/ROOT/images/devnotes/example-demo-app-included-modules.png
diff --git
a/viewers/graphql/adoc/modules/graphql/images/devnotes/graphql-included-modules.png
b/viewers/graphql/adoc/modules/ROOT/images/devnotes/graphql-included-modules.png
similarity index 100%
rename from
viewers/graphql/adoc/modules/graphql/images/devnotes/graphql-included-modules.png
rename to
viewers/graphql/adoc/modules/ROOT/images/devnotes/graphql-included-modules.png
diff --git a/viewers/graphql/adoc/modules/graphql/nav.adoc
b/viewers/graphql/adoc/modules/ROOT/nav.adoc
similarity index 100%
rename from viewers/graphql/adoc/modules/graphql/nav.adoc
rename to viewers/graphql/adoc/modules/ROOT/nav.adoc
diff --git a/viewers/graphql/adoc/modules/graphql/pages/about.adoc
b/viewers/graphql/adoc/modules/ROOT/pages/about.adoc
similarity index 61%
rename from viewers/graphql/adoc/modules/graphql/pages/about.adoc
rename to viewers/graphql/adoc/modules/ROOT/pages/about.adoc
index b88b8b788a..fe1ed0099b 100644
--- a/viewers/graphql/adoc/modules/graphql/pages/about.adoc
+++ b/viewers/graphql/adoc/modules/ROOT/pages/about.adoc
@@ -1,10 +1,13 @@
-= GraphQL (Incubating)
+= GraphQL Viewer
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with this work
for additional information regarding copyright ownership. The ASF licenses this
file to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by
applicable law or ag [...]
-The purpose of the GraphQL viewer is to automatically expose a
link:https://graphql.org/[graphql] API, based on the underlying metamodel.
-This of it as doing for GraphQL what the xref:vro::about.adoc[] does for REST.
+The GraphQL viewer automatically exposes an Apache Causeway domain object
model as a link:https://graphql.org/[graphql] API.
+It is implemented using link:https://spring.io/projects/spring-graphql[Spring
GraphQL] project, which in turn is built on top of
link:https://www.graphql-java.com/[GraphQL Java].
-An initial (currently incomplete) spcification of the API resides at
link:https://graphqlobjects.org[].
+
+== See also
+
+As well as this viewer, Apache Causeway also provides the
xref:vro::about.adoc[], which performs the same function, but using REST
instead of GraphQL.
diff --git
a/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc
b/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc
new file mode 100644
index 0000000000..ac2c75a037
--- /dev/null
+++ b/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -0,0 +1,54 @@
+= Setup and Configuration
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with this work
for additional information regarding copyright ownership. The ASF licenses this
file to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by
applicable law or ag [...]
+
+
+This section describes how to include the GraphQL viewer's module and set its
configuration properties.
+
+
+include::docs:mavendeps:partial$setup-and-configure-mavendeps-webapp.adoc[leveloffset=+1]
+
+
+== Update AppManifest
+
+In your application's `AppManifest` (top-level Spring `@Configuration` used to
bootstrap the app), import the
+
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ ...
+ CausewayModuleViewerGraphQlViewer.class,
+ ...
+})
+public class AppManifest {
+}
+----
+
+
+== Configuration Properties
+
+The xref:refguide:config:about.adoc[Configuration Guide] includes a
xref:refguide:config:sections/causeway.viewer.graphql.adoc[section] for the
GraphQL viewer.
+
+
+//
+// TODO: this is copied from RO API, commented out just to see structure.
+//
+// === Standard
+//
+// Standard configuration properties:
+//
+// *
xref:refguide:config:sections/causeway.viewer.restfulobjects.adoc#causeway.viewer.restfulobjects.base-uri[causeway.viewer.restfulobjects.base-uri]
+//
+// *
xref:refguide:config:sections/causeway.viewer.restfulobjects.adoc#causeway.viewer.restfulobjects.authentication.strategy-class-name[causeway.viewer.restfulobjects.authentication.strategy-class-name]
+// +
+// Security is discussed in more detail xref:security.adoc[here].
+//
+// *
xref:refguide:config:sections/causeway.viewer.restfulobjects.adoc#causeway.viewer.restfulobjects.strict-accept-checking[causeway.viewer.restfulobjects.strict-accept-checking]
+//
+// *
xref:refguide:config:sections/causeway.viewer.restfulobjects.adoc#causeway.viewer.restfulobjects.honor-ui-hints[causeway.viewer.restfulobjects.honor-ui-hints]
+//
+
+
+
diff --git a/viewers/graphql/adoc/modules/ROOT/partials/component-nav.adoc
b/viewers/graphql/adoc/modules/ROOT/partials/component-nav.adoc
new file mode 100644
index 0000000000..daa7cf0c56
--- /dev/null
+++ b/viewers/graphql/adoc/modules/ROOT/partials/component-nav.adoc
@@ -0,0 +1,5 @@
+
+
+
+include::gqlv:ROOT:partial$module-nav.adoc[]
+
diff --git a/viewers/graphql/adoc/modules/ROOT/partials/module-nav.adoc
b/viewers/graphql/adoc/modules/ROOT/partials/module-nav.adoc
new file mode 100644
index 0000000000..59f7350cc6
--- /dev/null
+++ b/viewers/graphql/adoc/modules/ROOT/partials/module-nav.adoc
@@ -0,0 +1,3 @@
+
+* xref:gqlv:ROOT:setup-and-configuration.adoc[]
+
diff --git a/viewers/graphql/adoc/modules/graphql/pages/devnotes.adoc
b/viewers/graphql/adoc/modules/graphql/pages/devnotes.adoc
deleted file mode 100644
index 8d98d7029d..0000000000
--- a/viewers/graphql/adoc/modules/graphql/pages/devnotes.adoc
+++ /dev/null
@@ -1,96 +0,0 @@
-= How to setup Dev Environment
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with this work
for additional information regarding copyright ownership. The ASF licenses this
file to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by
applicable law or ag [...]
-
-To speed up development it makes sense to only have the IDE build the stuff
that's needed.
-The approach I use is to have Maven perform a full build of everything, more
or less (including the xref:docs:referenceapp:about.adoc[reference app]), so
that the local cache in `~/.m2/repository` is up-to-date.
-Then, in the IDE, exclude the parts that won't change and include in the
relevant parts of the reference app (which we can use to iterate on).
-
-== Maven Build
-
-Perform a full mvn build, but exclude all of the incubator modules and
explicitly bring in this module.
-Also include the 'wicket' variant of the
xref:docs:referenceapp:about.adoc[reference app], as this also includes the
graphql viewer (as well as the RO viewer).
-
-[source,bash]
-----
-mvn install \
- -D module-examples-demo-wicket \
- -D module-incubator-graphql \
- -D skipTests
-----
-
-
-== IntelliJ
-
-In IntelliJ, ignore most of the projects except the ones to be changed or will
want to read (eg core).
-Also, explicit _include_ the relevant parts of the
xref:docs:referenceapp:about.adoc[reference app] (chances are that this will be
excluded initially due to the default profiles.
-
-Thus:
-
-* exclude `api` (`applib` and `schema`)
-+
-I find that IntelliJ can mess up with compiling applib as it depends on DTO
classes in schema generated by the mvn maven-jaxb2-plugin plugin; since they
change very infrequently, easier to simply pick them up as prebuilt libraries
from `~/.m2/repository`.
-
-* include `causeway-parent`
-
-* include `mavendeps/webapp`
-
-* include `commons`
-
-* include all of `core`
-+
-for the `metamodel`, `interaction` and `runtime`/`runtimeservices`.
-Since that is the bulk of core, it's easiest to include everything.
-
-* include `viewers/common`
-+
-as it makes sense for this to be a dependency
-
-* include `incubator/viewers/graphql` (of course!)
-+
-image::devnotes/graphql-included-modules.png[width=300px]
-
-* optionally include `viewers/restfulobjects`
-+
-for a bit of "monkey see, monkey do"
-
-* exclude everything else
-
-Then, (having also cloned the
link:https://github.com/apache/causeway-app-reference[github repo] for the
xref:docs:referenceapp:about.adoc[reference app] add in its paths:
-
-image::devnotes/example-demo-app-included-modules.png[width=300px]
-
-That is:
-
-* include `domain`
-* include `web`
-* include `wicket/demo-wicket-common`
-* include `wicket/demo-wicket-jpa`
-+
-this is where the SpringApplication -- `DemoAppWicketJpa` -- resides.
-It's faster to use the jpa variant rather than the jdo variant; no need to
wait for the DN enhancer.
-+
-[TIP]
-====
-you'll notice that examples/demo/domain has both Jdo and Jpa entities.
-These are both compiled, however at runtime the Jdo variants are ignored
because the `DemoAppWicketJpa` explicitly sets the "demo-jpa" Spring profile:
-
-[source,java]
-----
-System.setProperty("spring.profiles.active", "demo-jpa");
-----
-====
-
-[WARNING]
-====
-TODO:
-
-* use interfaces
-** the beansort ABSTRACT could be implemented as gql interface
-** for input types for interfaces (like PaperClip) we could create a mutator
for each implementation (f.e. addClipA, addClipB,..)
-====
-
-
-
-
-
diff --git a/viewers/graphql/adoc/modules/graphql/partials/module-nav.adoc
b/viewers/graphql/adoc/modules/graphql/partials/module-nav.adoc
deleted file mode 100644
index e7d77cf7a4..0000000000
--- a/viewers/graphql/adoc/modules/graphql/partials/module-nav.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-
-* xref:incubator:graphql:about.adoc[GraphQL]
-** xref:incubator:graphql:devnotes.adoc[Development Environment]
-
diff --git
a/viewers/graphql/applib/src/main/java/org/apache/causeway/viewer/graphql/applib/CausewayModuleIncViewerGraphqlApplib.java
b/viewers/graphql/applib/src/main/java/org/apache/causeway/viewer/graphql/applib/CausewayModuleViewerGraphqlApplib.java
similarity index 95%
rename from
viewers/graphql/applib/src/main/java/org/apache/causeway/viewer/graphql/applib/CausewayModuleIncViewerGraphqlApplib.java
rename to
viewers/graphql/applib/src/main/java/org/apache/causeway/viewer/graphql/applib/CausewayModuleViewerGraphqlApplib.java
index c6df389438..b8f0dfc621 100644
---
a/viewers/graphql/applib/src/main/java/org/apache/causeway/viewer/graphql/applib/CausewayModuleIncViewerGraphqlApplib.java
+++
b/viewers/graphql/applib/src/main/java/org/apache/causeway/viewer/graphql/applib/CausewayModuleViewerGraphqlApplib.java
@@ -25,6 +25,6 @@ import org.springframework.context.annotation.Import;
@Import({
// Modules
})
-public class CausewayModuleIncViewerGraphqlApplib {
+public class CausewayModuleViewerGraphqlApplib {
}
diff --git
a/viewers/graphql/model/src/main/java/org/apache/causeway/viewer/graphql/model/CausewayModuleIncViewerGraphqlModel.java
b/viewers/graphql/model/src/main/java/org/apache/causeway/viewer/graphql/model/CausewayModuleViewerGraphqlModel.java
similarity index 85%
rename from
viewers/graphql/model/src/main/java/org/apache/causeway/viewer/graphql/model/CausewayModuleIncViewerGraphqlModel.java
rename to
viewers/graphql/model/src/main/java/org/apache/causeway/viewer/graphql/model/CausewayModuleViewerGraphqlModel.java
index ef2a2437b3..0519549d03 100644
---
a/viewers/graphql/model/src/main/java/org/apache/causeway/viewer/graphql/model/CausewayModuleIncViewerGraphqlModel.java
+++
b/viewers/graphql/model/src/main/java/org/apache/causeway/viewer/graphql/model/CausewayModuleViewerGraphqlModel.java
@@ -22,14 +22,14 @@ import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
-import
org.apache.causeway.viewer.graphql.applib.CausewayModuleIncViewerGraphqlApplib;
+import
org.apache.causeway.viewer.graphql.applib.CausewayModuleViewerGraphqlApplib;
@Configuration
@Import({
// Modules
- CausewayModuleIncViewerGraphqlApplib.class
+ CausewayModuleViewerGraphqlApplib.class
})
@ComponentScan
-public class CausewayModuleIncViewerGraphqlModel {
+public class CausewayModuleViewerGraphqlModel {
}
diff --git
a/viewers/graphql/test/src/test/java/org/apache/causeway/viewer/graphql/viewer/test/CausewayViewerGraphqlTestModuleIntegTestAbstract.java
b/viewers/graphql/test/src/test/java/org/apache/causeway/viewer/graphql/viewer/test/CausewayViewerGraphqlTestModuleIntegTestAbstract.java
index 7e40dae0ae..01d7e2abb4 100644
---
a/viewers/graphql/test/src/test/java/org/apache/causeway/viewer/graphql/viewer/test/CausewayViewerGraphqlTestModuleIntegTestAbstract.java
+++
b/viewers/graphql/test/src/test/java/org/apache/causeway/viewer/graphql/viewer/test/CausewayViewerGraphqlTestModuleIntegTestAbstract.java
@@ -66,7 +66,7 @@ import
org.apache.causeway.core.runtimeservices.CausewayModuleCoreRuntimeService
import
org.apache.causeway.persistence.jpa.eclipselink.CausewayModulePersistenceJpaEclipselink;
import org.apache.causeway.security.bypass.CausewayModuleSecurityBypass;
import
org.apache.causeway.testing.fixtures.applib.CausewayModuleTestingFixturesApplib;
-import
org.apache.causeway.viewer.graphql.viewer.CausewayModuleIncViewerGraphqlViewer;
+import
org.apache.causeway.viewer.graphql.viewer.CausewayModuleViewerGraphqlViewer;
import org.apache.causeway.viewer.graphql.viewer.test.domain.UniversityModule;
import com.fasterxml.jackson.core.JsonProcessingException;
@@ -99,7 +99,7 @@ public abstract class
CausewayViewerGraphqlTestModuleIntegTestAbstract {
CausewayModuleSecurityBypass.class,
CausewayModulePersistenceJpaEclipselink.class,
CausewayModuleTestingFixturesApplib.class,
- CausewayModuleIncViewerGraphqlViewer.class,
+ CausewayModuleViewerGraphqlViewer.class,
UniversityModule.class
})
diff --git
a/viewers/graphql/viewer/src/main/java/org/apache/causeway/viewer/graphql/viewer/CausewayModuleIncViewerGraphqlViewer.java
b/viewers/graphql/viewer/src/main/java/org/apache/causeway/viewer/graphql/viewer/CausewayModuleViewerGraphqlViewer.java
similarity index 86%
rename from
viewers/graphql/viewer/src/main/java/org/apache/causeway/viewer/graphql/viewer/CausewayModuleIncViewerGraphqlViewer.java
rename to
viewers/graphql/viewer/src/main/java/org/apache/causeway/viewer/graphql/viewer/CausewayModuleViewerGraphqlViewer.java
index 9703764508..ae85d6e6da 100644
---
a/viewers/graphql/viewer/src/main/java/org/apache/causeway/viewer/graphql/viewer/CausewayModuleIncViewerGraphqlViewer.java
+++
b/viewers/graphql/viewer/src/main/java/org/apache/causeway/viewer/graphql/viewer/CausewayModuleViewerGraphqlViewer.java
@@ -18,13 +18,6 @@
*/
package org.apache.causeway.viewer.graphql.viewer;
-import graphql.ExceptionWhileDataFetching;
-import graphql.GraphQLError;
-
-import java.util.ArrayList;
-import java.util.List;
-import java.util.stream.Collectors;
-
import
org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.graphql.GraphQlAutoConfiguration;
import org.springframework.boot.autoconfigure.graphql.GraphQlCorsProperties;
@@ -38,14 +31,14 @@ import org.springframework.context.annotation.Import;
import org.springframework.graphql.execution.BatchLoaderRegistry;
import org.springframework.graphql.execution.DefaultBatchLoaderRegistry;
-import
org.apache.causeway.viewer.graphql.model.CausewayModuleIncViewerGraphqlModel;
+import
org.apache.causeway.viewer.graphql.model.CausewayModuleViewerGraphqlModel;
@Configuration
@Import({
// @Service's
// Modules
- CausewayModuleIncViewerGraphqlModel.class,
+ CausewayModuleViewerGraphqlModel.class,
// autoconfigurations
GraphQlAutoConfiguration.class,
@@ -55,7 +48,7 @@ import
org.apache.causeway.viewer.graphql.model.CausewayModuleIncViewerGraphqlMo
GraphQlProperties.class, GraphQlCorsProperties.class
})
@ComponentScan
-public class CausewayModuleIncViewerGraphqlViewer {
+public class CausewayModuleViewerGraphqlViewer {
@Bean
@ConditionalOnMissingBean
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
b/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
index 3254d0d7d7..d78575146e 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
@@ -10,6 +10,11 @@ Most significant of these is enhanced content negotiation
support, making it eas
This component guide discuss features, configuration and also how to extend
the Restful Objects viewer.
+== See also
+
+As well as this viewer, Apache Causeway also provides the
xref:gqlv::about.adoc[], which performs the same function, but using GraphQL
instead of REST.
+
+
