GraphiQL

GraphiQL is a graphical interactive in-browser GraphQL IDE. It is very popular amongst developers as it makes it easy to explore and interactively develop GraphQL APIs. During development, a stock GraphiQL integration is often enough to help developers work on an API. In production, applications can require a custom GraphiQL build, that ships with a company logo or specific authentication support.

Spring for GraphQL ships with a stock GraphiQL index.html page that uses static resources hosted on the unpkg.com CDN. Spring Boot applications can easily enable this page with a configuration property.

Your application may need a custom GraphiQL build if it requires a setup that doesn’t rely on a CDN, or if you wish to customize the user interface. This can be done in two steps:

  1. Configure and compile a GraphiQL build

  2. Expose the built GraphiQL instance through the Spring web infrastructure

Creating a custom GraphiQL build

This part is generally outside of the scope of this documentation, as there are several options for custom builds. You will find more information in the official GraphiQL documentation. You can choose to copy the build result directly in your application resources. Alternatively, you can integrate the JavaScript build in your project as a separate module by leveraging Node.js Gradle or Maven build plugins.

Exposing a GraphiQL instance

Once a GraphiQL build is available on the classpath, you can expose it as an endpoint with the functional web frameworks.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.core.io.ClassPathResource;
import org.springframework.graphql.server.webmvc.GraphiQlHandler;
import org.springframework.web.servlet.function.RouterFunction;
import org.springframework.web.servlet.function.RouterFunctions;
import org.springframework.web.servlet.function.ServerResponse;

@Configuration
public class GraphiQlConfiguration {

	@Bean
	@Order(0)
	public RouterFunction<ServerResponse> graphiQlRouterFunction() {
		RouterFunctions.Builder builder = RouterFunctions.route();
		ClassPathResource graphiQlPage = new ClassPathResource("graphiql/index.html"); (1)
		GraphiQlHandler graphiQLHandler = new GraphiQlHandler("/graphql", "", graphiQlPage); (2)
		builder = builder.GET("/graphiql", graphiQLHandler::handleRequest); (3)
		return builder.build(); (4)
	}
}
1 Load the GraphiQL page from the classpath (here, we are using the version shipped with Spring for GraphQL)
2 Configure a web handler for processing HTTP requests; you can implement a custom HandlerFunction depending on your use case
3 Finally, map the handler to a specific HTTP endpoint
4 Expose this new route through a RouterFunction bean

You might also need to configure your application to serve the relevant static resources.