Setup and Configuration

This section describes how to include the GraphQL viewer’s module and set its configuration properties.

Maven pom.xml

Dependency Management

If your application inherits from the Apache Causeway starter app (org.apache.causeway.app:causeway-app-starter-parent) then that will define the version automatically:

pom.xml
<parent>
    <groupId>org.apache.causeway.app</groupId>
    <artifactId>causeway-app-starter-parent</artifactId>
    <version>3.1.0</version>
    <relativePath/>
</parent>

Alternatively, import the core BOM. This is usually done in the top-level parent pom of your application:

pom.xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.causeway.core</groupId>
            <artifactId>causeway-core</artifactId>
            <version>3.1.0</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

Dependency

In the webapp module of your application, add the following dependency:

pom.xml
<dependencies>
    <dependency>
        <groupId>org.apache.causeway.mavendeps</groupId>
        <artifactId>causeway-mavendeps-webapp</artifactId>
        <type>pom</type>
    </dependency>
</dependencies>

Update AppManifest

In your application’s AppManifest (top-level Spring @Configuration used to bootstrap the app), import the

AppManifest.java
@Configuration
@Import({
        ...
        CausewayModuleViewerGraphQlViewer.class,
        ...
})
public class AppManifest {
}

Configuration Properties

The configuration properties for the GraphQL viewer fall into a number of categories.

(To make this section easier to read, the causeway.viewer.graphql. prefix of all of these configuration properties is omitted).

API variant and Schema Style

The most important configuration properties are:

  • api-variant

    Whether to support relaxed (but non-spec compliant) queries with mutations, or instead to expose an API that is query only.

  • api-scope

    Whether to include all domain classes in the GraphQL schema (entities and view models), or whether only to include view models. Which to use depends upon whether the GraphQL client is owned by the same team the owns the backend application.

  • schema-style

    Whether to use the "simple" schema style (data only, client-driven), the "rich" schema style (includes supporting facets, server-driven) or both schema styles.

These were discussed on the main page for GraphQL viewer.

Customizing the Schema

A number of other configuration properties can customize the schema in various ways. Normally these can be left as their default:

  • schema.simple.top-level-field-name

    If using the SIMPLE_AND_RICH or RICH_AND_SIMPLE schema styles, this configuration defines the name of the top-level field that holds the rest of the simple schema.

    It defaults to “simple”.

  • schema.rich.top-level-field-name

    If using the SIMPLE_AND_RICH or RICH_AND_SIMPLE schema styles, this configuration defines the name of the top-level field that holds the rest of the rich schema.

    It defaults to “rich”.

  • meta-data.field-name

    Defines the field name of the "meta data" structure used to expose the id, logical type name and (for entities) the version of a domain object.

    The default value for this config property is “_meta”.

The schema to look up a domain object can also be customized:

  • lookup.arg-name

    This is the name of the synthetic first argument used to locate the object to be looked up.

    It defaults to “object”.

  • lookup.field-name-prefix

    Whether to prefix the field name of the domain object’s type.

    This defaults to an empty string, in other words no prefix.

  • lookup.field-name-suffix

    Whether to add a suffix to the field name of the domain object’s type.

    This defaults to an empty string, in other words no suffix.

If executing a mutation rather than a query:

  • mutation.target-arg-name

    This is the name of the synthetic first argument used to locate the object to be mutated.

    It defaults to “_target”.

The remaining configuration properties are explained in more detail elsewhere:

Marshalling SPI: