Table of Contents

• GraphQL Spring Framework Boot Starter
• Intro
• Requires
• Enable GraphQL Server
• Enable GraphiQL Tool
• Contributions
• License

GraphQL and GraphiQL Spring Framework Boot Starters

GraphQL Starter

GraphiQL Starter

Intro

Repository contains:

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

Requires

• Java 1.8
• Spring Framework GraphQL Common Library
• Spring Framework Boot 1.3.x (web)

Add repository:

repositories {
    // stable build
    jcenter()
    // development build
    maven { url  "http://dl.bintray.com/oembedler/maven" }
}

Dependency:

dependencies {
  compile 'com.embedler.moon.graphql.boot:graphql-spring-boot-starter:INSERT_LATEST_VERSION_HERE'
  
  // to embed GraphiQL tool
  compile 'com.embedler.moon.graphql.boot:graphiql-spring-boot-starter:INSERT_LATEST_VERSION_HERE'
}

How to use the latest build with Maven:

<repository>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
    <id>bintray-oembedler-maven</id>
    <name>bintray</name>
    <url>http://dl.bintray.com/oembedler/maven</url>
</repository>

Dependency:

<dependency>
    <groupId>com.embedler.moon.graphql.boot</groupId>
    <artifactId>graphql-spring-boot-starter</artifactId>
    <version>INSERT_LATEST_VERSION_HERE</version>
</dependency>

<!-- to embed GraphiQL tool -->
<dependency>
    <groupId>com.embedler.moon.graphql.boot</groupId>
    <artifactId>graphiql-spring-boot-starter</artifactId>
    <version>INSERT_LATEST_VERSION_HERE</version>
</dependency>

Enable GraphQL Server

Server becomes accessible at /graphql if graphql-spring-boot-starter added as a dependency to a boot application and @EnableGraphQLServer annotation is set at the main java configuration class. GraphQL schemas are automatically discovered extracting all classes from Spring context marked as @GraphQLSchema.

Request parameters:

• query: A string GraphQL document to be executed.

• variables: The runtime values to use for any GraphQL query variables as a JSON object.

• operationName: If the provided query contains multiple named operations, this specifies which operation should be executed. If not provided, an error will be returned if the query contains multiple named operations.

GraphQL will first look for each parameter in the URL's query-string:

/graphql?query=query+getUser($id:ID){user(id:$id){name}}&variables={"id":"4"}

If not found in the query-string, it will look in the POST request body.

Server uses [commons-fileupload][] middleware to add support for multipart/form-data content, which may be useful for GraphQL mutations involving uploading files (see test application for more details). GraphQLContext is a map of objects (context) for the current query execution. In order to get access to uploaded file com.oembedler.moon.graphql.boot.GraphQLContext should be passed as input parameter to datafetcher or mutation (don't need to be annotated). Calling method GraphQLContext.getUploadedFile() returns instance of MultipartFile.

If the POST body has not yet been parsed, graphql-express will interpret it depending on the provided Content-Type header.

• application/json: the POST body will be parsed as a JSON object of parameters.

• application/x-www-form-urlencoded: this POST body will be parsed as a url-encoded string of key-value pairs.

• multipart/form-data: this POST body will be parsed as a string of key-value pairs and it supports file upload (see above).

• application/graphql: The POST body will be parsed as GraphQL query string, which provides the query parameter.

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

Server can host multiple schemas (all are registered at the startup time).

To run query against particular schema - HTTP header graphql-schema parameter passed along with the query should contain graphql schema name of interest.

graphql:
      server:
               mapping: /graphql
               corsEnabled: true
               suppressSpringResponseCodes: true
               query-key: query
               variables-key: variables
               uploadMaxFileSize: 128KB
               uploadMaxRequestSize: 128KB
      schema:
               clientMutationIdName: clientMutationId
               injectClientMutationId: true
               allowEmptyClientMutationId: false
               mutationInputArgumentName: input
               outputObjectNamePrefix: Payload
               inputObjectNamePrefix: Input
               schemaMutationObjectName: Mutation

To facilitate access from Nodejs frontend to GraphQL backend by default system enables global CORS filter for /graphql/** context. The corsEnabled can be set to false to disable it.

By default system register GlobalDefaultExceptionHandler which suppresses Spring framework error responses and responds with standard GraphQL server error. Application configuration suppressSpringResponseCodes property can be set to false to disable that handler.

Enable GraphiQL Tool

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

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

Contributions

Contributions are welcome.

Tips:

• Respect the Code of Conduct.
• Before opening an Issue to report a bug, please try the latest development version. It might happen that the problem is already solved.
• Please use Markdown to format your comments properly. If you are not familiar with that: Getting started with writing and formatting on GitHub
• For Pull Requests:
  • Here are some general tips
  • Please be a as focused and clear as possible and don't mix concerns. This includes refactorings mixed with bug-fixes/features, see Open Source Contribution Etiquette
  • It would be good to add an automatic test(s).

License

graphql-spring-boot-starter and graphiql-spring-boot-starter are licensed under the MIT License. See LICENSE for details.

spring-graphql-common License

graphql-java License

graphiql License

graphql-js License