Merge pull request #251 from BlasiusSecundus/feature/playground-integration

Added GraphQL Playground starter

Author: oliemansm

README.md

@@ -7,17 +7,24 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**
 
-- [GraphQL and Graph*i*QL Spring Framework Boot Starters](#graphql-and-graphiql-spring-framework-boot-starters)
   - [WARNING: NoClassDefFoundError when using GraphQL Java Tools > 5.4.x](#warning-noclassdeffounderror-when-using-graphql-java-tools--54x)
     - [Using Gradle](#using-gradle)
     - [Using Maven](#using-maven)
 - [Documentation](#documentation)
 - [Requirements and Downloads](#requirements-and-downloads)
 - [Enable GraphQL Servlet](#enable-graphql-servlet)
 - [Enable Graph*i*QL](#enable-graphiql)
+- [Enable Altair](#enable-altair)
+- [Enable GraphQL Playground](#enable-graphql-playground)
+  - [Basic settings](#basic-settings)
+  - [CDN](#cdn)
+  - [Custom static resources](#custom-static-resources)
+  - [Customizing GraphQL Playground](#customizing-graphql-playground)
+  - [Tabs](#tabs)
 - [Supported GraphQL-Java Libraries](#supported-graphql-java-libraries)
   - [GraphQL Java Tools](#graphql-java-tools)
 - [Tracing and Metrics](#tracing-and-metrics)
+  - [Usage](#usage)
 - [Contributions](#contributions)
 - [Licenses](#licenses)
 
@@ -55,6 +62,7 @@ Repository contains:
 * `graphql-spring-boot-starter` to turn your boot application into GraphQL server (see [graphql-java-servlet](https://github.com/graphql-java-kickstart/graphql-java-servlet))
 * `altair-spring-boot-starter`to embed `Altair` tool for schema introspection and query debugging (see [altair](https://github.com/imolorhe/altair))
 * `graphiql-spring-boot-starter`to embed `GraphiQL` tool for schema introspection and query debugging (see [graphiql](https://github.com/graphql/graphiql))
+* `playground-spring-boot-starter`to embed `GraphQL Playground` tool for schema introspection and query debugging (see [GraphQL Playground](https://github.com/prisma/graphql-playground))
 * `voyager-spring-boot-starter`to embed `Voyager` tool for visually explore GraphQL APIs as an interactive graph (see [voyger](https://github.com/APIs-guru/graphql-voyager))
 
 # Requirements and Downloads
@@ -251,6 +259,102 @@ to set the classpath resources that should be loaded.
 
 Headers that are used when sending the Altair queries can be set by defining them in the `altair.headers` group.
 
+# Enable GraphQL Playground
+
+GraphQL Playground becomes accessible at root `/playground` (or as configured in `graphql.playground.mapping`) 
+if `playground-spring-boot-starter` is added as a dependency to a boot application. 
+
+It uses an embedded `GraphQL Playground React`, in accordance to the [official guide](https://github.com/prisma/graphql-playground#as-html-page),
+using the 'minimum HTML' approach.
+
+Available Spring Boot configuration parameters (either `application.yml` or `application.properties`):
+
+```yaml
+graphql.playground:
+    mapping: /playground
+    endpoint: /graphql
+    subscriptionsEndpoint: /subscriptions
+    staticFolder.basePath: my-playground-resources-folder
+    enabled: true
+    pageTitle: Playground
+    cdn:
+        enabled: false
+        version: latest
+    settings:
+        editor.cursorShape: line
+        editor.fontFamily: "'Source Code Pro', 'Consolas', 'Inconsolata', 'Droid Sans Mono', 'Monaco', monospace"
+        editor.fontSize: 14
+        editor.reuseHeaders: true
+        editor.theme: dark
+        general.betaUpdates: false
+        prettier.printWidth: 80
+        prettier.tabWidth: 2
+        prettier.useTabs: false
+        request.credentials: omit
+        schema.polling.enable: true
+        schema.polling.endpointFilter: "*localhost*"
+        schema.polling.interval: 2000
+        schema.disableComments: true
+        tracing.hideTracingResponse: true
+    headers:
+        headerFor: AllTabs
+    tabs:
+        - name: Example Tab
+          query: classpath:exampleQuery.graphql
+          headers:
+            SomeHeader: Some value
+          variables: classpath:variables.json
+          responses:
+            - classpath:exampleResponse1.json
+            - classpath:exampleResponse2.json
+```
+## Basic settings
+
+`mapping`, `endpoint` and `subscriptionsEndpoint` will default to `/playground`, `/graphql` and `/subscriptions`, 
+respectively. Note that these values may not be empty.
+
+`enabled` defaults to `true`, and therefor Playground will be available by default if the dependency is added to a
+ Spring Boot Web Application project.
+
+`pageTitle` defaults to `Playground`.
+
+`headers` allows you to specify headers for the default tab. Note that if your are using Spring Security and CSRF is 
+enabled CSRF, the CSRF token will be automatically added to the headers. These headers will also be added to all the tabs
+configured under the [Tabs](#tabs) section. If a header is defined both in this 'global' header list and the header list
+of the individual tabs, the 'local' version will be used for that tab. 
+
+## CDN
+
+The currently bundled version is `1.7.20`, which is - as of writing this - the latest release of `GraphQL Playground React`. 
+The CDN option uses `jsDelivr` CDN, if enabled. By default, it will load the latest available release.
+Available CDN versions can be found on the project's 
+[jsDelivr page](https://www.jsdelivr.com/package/npm/graphql-playground-react). The CDN option is disabled by default.
+
+## Custom static resources
+
+You can also specify a custom local version of Playground by setting the base path for `Playground` resources in
+the `staticPath.base` property. Under this directory, you have to provide the following files:
+   
+* `static/css/index.css`
+* `static/js/middleware.js`
+* `favicon.png`
+* `logo.png`
+
+This is identical to the directory structure of the CDN under the `build` subfolder (where these files can be found).
+
+## Customizing GraphQL Playground
+
+Further GraphQL Playground settings can be specified under the `settings` group, which are documented in the official 
+[GraphQL Playground readme](https://github.com/prisma/graphql-playground#settings). Note that enum-like values are 
+validated against the available options, and your application will not start if wrong settings are provided. Similarly
+there is some basic validation for integer values (they must be valid positive integers).
+
+## Tabs
+
+Optionally, you can specify tabs that will be present when the user first opens GraphQL Playground. You can configure the 
+query, variables, headers and even supply sample responses. Note that `query`, `variables` and `responses` are expected
+to be resources of the appropriate format (GraphQL for `query`, JSON for `variables` and `responses`). 
+
 # Supported GraphQL-Java Libraries
 
 The following libraries have auto-configuration classes for creating a `GraphQLSchema`.

build.gradle

@@ -187,7 +187,9 @@ release {
             'com.graphql-java-kickstart:graphql-spring-boot-test',
             'com.graphql-java-kickstart:graphql-spring-boot-test-autoconfigure',
             'com.graphql-java-kickstart:voyager-spring-boot-autoconfigure',
-            'com.graphql-java-kickstart:voyager-spring-boot-starter'
+            'com.graphql-java-kickstart:voyager-spring-boot-starter',
+            'com.graphql-java-kickstart:playgroud-spring-boot-autoconfigure',
+            'com.graphql-java-kickstart:playgroud-spring-boot-starter'
     ]
 }
 

playground-spring-boot-autoconfigure/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Oembedler Inc. and Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

playground-spring-boot-autoconfigure/build.gradle

@@ -0,0 +1,32 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016 oEmbedler Inc. and Contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ *  documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ *  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ *  persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+ * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+dependencies{
+    annotationProcessor "org.springframework.boot:spring-boot-configuration-processor:$LIB_SPRING_BOOT_VER"
+    
+    compile "org.springframework.boot:spring-boot-autoconfigure:$LIB_SPRING_BOOT_VER"
+    compile "org.springframework.boot:spring-boot-starter-web:$LIB_SPRING_BOOT_VER"
+    compile "org.springframework.boot:spring-boot-starter-thymeleaf:$LIB_SPRING_BOOT_VER"
+
+    testCompile "org.springframework.boot:spring-boot-starter-web:$LIB_SPRING_BOOT_VER"
+    testCompile "org.springframework.boot:spring-boot-starter-test:$LIB_SPRING_BOOT_VER"
+    testCompile "org.springframework.boot:spring-boot-starter-security:$LIB_SPRING_BOOT_VER"
+    testCompile "org.jsoup:jsoup:1.12.1"
+}
+
+compileJava.dependsOn(processResources)

playground-spring-boot-autoconfigure/src/main/java/com/oembedler/moon/playground/boot/PlaygroundAutoConfiguration.java

@@ -0,0 +1,24 @@
+package com.oembedler.moon.playground.boot;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.DispatcherServlet;
+
+@Configuration
+@ConditionalOnWebApplication
+@ConditionalOnClass(DispatcherServlet.class)
+@EnableConfigurationProperties(PlaygroundPropertiesConfiguration.class)
+public class PlaygroundAutoConfiguration {
+
+    @Bean
+    @ConditionalOnProperty(value = "graphql.playground.enabled", havingValue = "true", matchIfMissing = true)
+    PlaygroundController playgroundController(final PlaygroundPropertiesConfiguration playgroundPropertiesConfiguration,
+            final ObjectMapper objectMapper) {
+        return new PlaygroundController(playgroundPropertiesConfiguration, objectMapper);
+    }
+}

playground-spring-boot-autoconfigure/src/main/java/com/oembedler/moon/playground/boot/PlaygroundController.java

@@ -0,0 +1,67 @@
+package com.oembedler.moon.playground.boot;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Controller;
+import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.GetMapping;
+
+import javax.servlet.http.HttpServletRequest;
+import java.nio.file.Paths;
+
+@Controller
+@RequiredArgsConstructor
+public class PlaygroundController {
+
+    private static final String CDN_ROOT = "https://cdn.jsdelivr.net/npm/graphql-playground-react";
+    private static final String CSS_PATH = "static/css/index.css";
+    private static final String FAVICON_PATH =  "favicon.png";
+    private static final String SCRIPT_PATH = "static/js/middleware.js";
+    private static final String LOGO_PATH = "logo.png";
+
+    private static final String CSS_URL_ATTRIBUTE_NAME = "cssUrl";
+    private static final String FAVICON_URL_ATTRIBUTE_NAME = "faviconUrl";
+    private static final String SCRIPT_URL_ATTRIBUTE_NAME = "scriptUrl";
+    private static final String LOGO_URL_ATTRIBUTE_NAME = "logoUrl";
+
+    private final PlaygroundPropertiesConfiguration propertiesConfiguration;
+
+    private final ObjectMapper objectMapper;
+
+    @GetMapping("${graphql.playground.mapping:/playground}")
+    public String playground(final Model model, final HttpServletRequest request) {
+        if (propertiesConfiguration.getPlayground().getCdn().isEnabled()) {
+            setCdnUrls(model);
+        } else {
+            setLocalAssetUrls(model);
+        }
+        model.addAttribute("pageTitle", propertiesConfiguration.getPlayground().getPageTitle());
+        model.addAttribute("properties", objectMapper.valueToTree(propertiesConfiguration.getPlayground()));
+        model.addAttribute("_csrf", request.getAttribute("_csrf"));
+        return "playground";
+    }
+
+    private String getCdnUrl(final String assetPath) {
+        return String.format("%s@%s/build/%s", CDN_ROOT, propertiesConfiguration.getPlayground().getCdn().getVersion(),
+                assetPath);
+    }
+
+    private String getLocalUrl(final String assetPath) {
+        return Paths.get(propertiesConfiguration.getPlayground().getStaticPath().getBase(), assetPath).toString()
+                .replace('\\', '/');
+    }
+
+    private void setCdnUrls(final Model model) {
+        model.addAttribute(CSS_URL_ATTRIBUTE_NAME, getCdnUrl(CSS_PATH));
+        model.addAttribute(FAVICON_URL_ATTRIBUTE_NAME, getCdnUrl(FAVICON_PATH));
+        model.addAttribute(SCRIPT_URL_ATTRIBUTE_NAME, getCdnUrl(SCRIPT_PATH));
+        model.addAttribute(LOGO_URL_ATTRIBUTE_NAME, getCdnUrl(LOGO_PATH));
+    }
+
+    private void setLocalAssetUrls(final Model model) {
+        model.addAttribute(CSS_URL_ATTRIBUTE_NAME, getLocalUrl(CSS_PATH));
+        model.addAttribute(FAVICON_URL_ATTRIBUTE_NAME, getLocalUrl(FAVICON_PATH));
+        model.addAttribute(SCRIPT_URL_ATTRIBUTE_NAME, getLocalUrl(SCRIPT_PATH));
+        model.addAttribute(LOGO_URL_ATTRIBUTE_NAME, getLocalUrl(LOGO_PATH));
+    }
+}

playground-spring-boot-autoconfigure/src/main/java/com/oembedler/moon/playground/boot/PlaygroundPropertiesConfiguration.java

@@ -0,0 +1,16 @@
+package com.oembedler.moon.playground.boot;
+
+import com.oembedler.moon.playground.boot.properties.PlaygroundProperties;
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+import org.springframework.validation.annotation.Validated;
+
+@Data
+@ConfigurationProperties(prefix = "graphql")
+@Validated
+public class PlaygroundPropertiesConfiguration {
+
+    @NestedConfigurationProperty
+    private PlaygroundProperties playground = new PlaygroundProperties();
+}

playground-spring-boot-autoconfigure/src/main/java/com/oembedler/moon/playground/boot/ResourceSerializer.java

@@ -0,0 +1,21 @@
+package com.oembedler.moon.playground.boot;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.databind.JsonSerializer;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import org.apache.tomcat.util.http.fileupload.util.Streams;
+import org.springframework.boot.jackson.JsonComponent;
+import org.springframework.core.io.Resource;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+@JsonComponent
+public class ResourceSerializer extends JsonSerializer<Resource> {
+    @Override
+    public void serialize(final Resource value, final JsonGenerator gen, final SerializerProvider serializers)
+            throws IOException {
+        final String content = Streams.asString(value.getInputStream(), StandardCharsets.UTF_8.name());
+        gen.writeString(content);
+    }
+}

playground-spring-boot-autoconfigure/src/main/java/com/oembedler/moon/playground/boot/properties/PlaygroundCdn.java

@@ -0,0 +1,13 @@
+package com.oembedler.moon.playground.boot.properties;
+
+import lombok.Data;
+
+import javax.validation.constraints.NotBlank;
+
+@Data
+public class PlaygroundCdn {
+
+    private boolean enabled;
+    @NotBlank
+    private String version = "latest";
+}

playground-spring-boot-autoconfigure/src/main/java/com/oembedler/moon/playground/boot/properties/PlaygroundProperties.java

@@ -0,0 +1,41 @@
+package com.oembedler.moon.playground.boot.properties;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import lombok.Data;
+import org.springframework.boot.context.properties.NestedConfigurationProperty;
+
+import javax.validation.constraints.NotBlank;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+@Data
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public class PlaygroundProperties {
+
+    @NotBlank
+    private String endpoint = "/graphql";
+
+    @NotBlank
+    private String subscriptionEndpoint = "/subscriptions";
+
+    @NestedConfigurationProperty
+    @JsonIgnore
+    private PlaygroundCdn cdn = new PlaygroundCdn();
+
+    @NestedConfigurationProperty
+    @JsonIgnore
+    private PlaygroundStaticPathSettings staticPath = new PlaygroundStaticPathSettings();
+
+    @JsonIgnore
+    private String pageTitle = "Playground";
+
+    @NestedConfigurationProperty
+    private PlaygroundSettings settings;
+
+    private Map<String, String> headers = Collections.emptyMap();
+
+    @NestedConfigurationProperty
+    private List<PlaygroundTab> tabs = Collections.emptyList();
+}