GraphQL and GraphiQL Spring Framework Boot Starters

Table of Contents

Intro

Repository contains:

graphql-spring-boot-starter to turn your boot application into GraphQL server (see graphql-java-servlet)
graphiql-spring-boot-starterto embed GraphiQL tool for schema introspection and query debugging (see graphiql)

Requirements and Downloads

Requirements:

Java 1.8
Spring Framework Boot > 2.x.x (web)

Gradle:

repositories {
    jcenter()
    mavenCentral()
}

dependencies {
  compile 'com.graphql-java-kickstart:graphql-spring-boot-starter:5.0.3'
  
  // to embed GraphiQL tool
  compile 'com.graphql-java-kickstart:graphiql-spring-boot-starter:5.0.3'

  // to embed Voyager tool
  compile 'com.graphql-java-kickstart:voyager-spring-boot-starter:5.0.3'
}

Maven:

<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-spring-boot-starter</artifactId>
    <version>5.0.3</version>
</dependency>

<!-- to embed GraphiQL tool -->
<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphiql-spring-boot-starter</artifactId>
    <version>5.0.3</version>
</dependency>

<!-- to embed Voyager tool -->
<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>voyager-spring-boot-starter</artifactId>
    <version>5.0.3</version>
</dependency>

New releases will be available faster in the JCenter repository than in Maven Central. Add the following to use for Maven

<repositories>
    <repository>
      <id>jcenter</id>
      <url>https://jcenter.bintray.com/</url>
    </repository>
</repositories>

For Gradle:

repositories {
    jcenter()
}

Enable GraphQL Servlet

The servlet becomes accessible at /graphql if graphql-spring-boot-starter added as a dependency to a boot application and a GraphQLSchema bean is present in the application. Check out the simple example for the bare minimum required.

A GraphQL schema can also be automatically created when a supported graphql-java schema library is found on the classpath.

See the graphql-java-servlet usage docs for the avaiable endpoints exposed.

Available Spring Boot configuration parameters (either application.yml or application.properties):

graphql:
      servlet:
               mapping: /graphql
               enabled: true
               corsEnabled: true

By default a global CORS filter is enabled for /graphql/** context. The corsEnabled can be set to false to disable it.

Enable GraphiQL

GraphiQL becomes accessible at the root /graphiql if graphiql-spring-boot-starter is added as a dependency to a boot application.

Note that GraphQL server must be available at /graphql/* context to be discovered by GraphiQL.

Available Spring Boot configuration parameters (either application.yml or application.properties):

graphiql:
    mapping: /graphiql
    endpoint:
      graphql: /graphql
      subscriptions: /subscriptions
    static:
      basePath: /
    enabled: true
    pageTitle: GraphiQL
    cdn:
        enabled: false
        version: 0.11.11
    props:
        resources:
            query: query.graphql
            defaultQuery: defaultQuery.graphql
            variables: variables.graphql
        variables:
            editorTheme: "solarized light"
    headers:
        Authorization: "Bearer <your-token>"

By default GraphiQL is served from within the package. This can be configured to be served from CDN instead, by setting the property graphiql.cdn.enabled to true.

You are able to set the GraphiQL props as well. The graphiql.props.variables group can contain any of the props as defined at GraphiQL Usage. Since setting (large) queries in the properties like this isn't very readable, you can use the properties in the graphiql.props.resources group to set the classpath resources that should be loaded.

Headers that are used when sending the GraphiQL queries can be set by defining them in the graphiql.headers group.

Supported GraphQL-Java Libraries

The following libraries have auto-configuration classes for creating a GraphQLSchema.

GraphQL Java Tools

https://github.com/graphql-java-kickstart/graphql-java-tools

All GraphQLResolver and GraphQLScalar beans, along with a bean of type SchemaParserDictionary (to provide all other classes), will be used to create a GraphQLSchema. Any files on the classpath named *.graphqls will be used to provide the schema definition. See the Readme for more info.

Available Spring Boot configuration parameters (either application.yml or application.properties):

graphql:
    tools:
        schemaLocationPattern: "**/*.graphqls"

By default GraphQL tools uses the location pattern **/*.graphqls to scan for GraphQL schemas on the classpath. Use the schemaLocationPattern property to customize this pattern.

GraphQL Spring Common [LATEST SUPPORTED VERSION: 3.1.1]

https://github.com/oembedler/spring-graphql-common

See the Readme and the example for usage instructions.

Application Properties

graphql:
      spring-graphql-common:
               clientMutationIdName: clientMutationId
               injectClientMutationId: true
               allowEmptyClientMutationId: false
               mutationInputArgumentName: input
               outputObjectNamePrefix: Payload
               inputObjectNamePrefix: Input
               schemaMutationObjectName: Mutation