Home

How to use it?

How to use it?

The full project documentation

The Full documentation is available here, on the github wiki. The main starter points are:

For the client mode, you'll find there a description on how to:

Start with a Spring app
Start with a non Spring app
Execute GraphQL requests with the help of this plugin
Personalize the generated code to add fields, or interface and annotation to classes (GraphQL types, input types, interfaces, unions and enums) and/or fields.
Customize the templates to change the templates that generate the code, according to your needs.
Access to an OAuth2 GraphQL server
Client migration from 1.x to 2.x

For the server mode, you'll find explanations on how to:

Build a GraphQL server with the help of this plugin
Implement subscriptions
Personalize the generated code to add fields, or interface and annotation to classes (GraphQL types, input types, interfaces, unions and enums) and/or fields.
Customize the templates to change the generated code, according to your needs.
Implement an OAuth2 GraphQL server
Server migration from 1.x to 2.x

The tutorials

Two tutorials are available for the Maven plugin:

The Client tutorial describes how to use this plugin, when building a GraphQL client. It's in the GraphQL-Forum-Maven-Tutorial-client project.
The Server tutorial describes how to build a GraphQL server in the GraphQL-Forum-Maven-Tutorial-server project.

The same two tutorials exist for the Gradle plugin:

The Client tutorial describes how to use this plugin, when building a GraphQL client. It's in the GraphQL-Forum-Gradle-Tutorial-client git repository.
The Server tutorial describes how to build a GraphQL server in the GraphQL-Forum-Gradle-Tutorial-server.

Samples

You'll find the following samples in the project. For all of these samples, there are two projects: the client and the server.

allGraphQLCases
- This project is a compilation of GraphQL capabilities ... that are managed by this plugin. Its main objective is to have lots of specific cases, for integration testing.
- The server is packaged as a Spring Boot application
- The GraphQL server exposes http
Forum
- The server is packaged as a Spring Boot application
- The GraphQL server exposes http
- The server uses the schema personalization, to override the default code generation
- The GraphQL model maps to the database model
- The Forum client project shows implementation of the same queries in the XxxQueries classes.
- This sample contains a subscription, on both the client and the server side
StarWars (only in the Maven plugin project)
- The server is packaged as a war
- The GraphQL server exposes https
- The GraphQL interfaces in this model (character, and friends relation) makes it difficult to map to native RDBMS data model. This project uses JPA native queries to overcome this.
- The StarWars client project shows implementation of the same queries in the XxxQueries classes.
- This sample contains a subscription, on both the client and the server side
CustomTemplates (only in the Maven plugin project)
- An example related on how to customize code templates
  - graphql-maven-plugin-samples-CustomTemplates-resttemplate project offers a customize template for Query/Mutation/Subscriptino client class and offer a Spring-base RestTemplate implementation for QueryExecutor template
  - graphql-maven-plugin-samples-CustomTemplates-resttemplate proyect defines a client project that generates code with customized template defined in previous project

Note: The client projects for these samples contain integration tests. They are part of the global build. These integration tests check the graphql-maven-plugin behaviour for both the client and the server for these samples.

Client mode

When in client mode, you can query the server with just one line of code.

For instance :

String id = [an id];

Human human = queryType.human("{id name appearsIn homePlanet friends{name}}", id);

You can use input types:

HumanInput input = new HumanInput();
... [some initialization of input content]

Human human = mutationType.createHuman("{id name appearsIn friends {id name}}", input);

In this mode, the plugin generates:

One java class for the Query object
One java class for the Mutation object (if any)
One POJO for each standard object of the GraphQL object
All the necessary runtime is actually attached as source code into your project: the generated code is stand-alone. So, your project, when it runs, doesn't depend on any external dependency from graphql-java-generator.

You'll find more information on the client page.

Server mode

When in server mode, the plugin generates:

The main class:
- When in a jar maven project, the main class to start a Spring Boot application
- When in a war maven project, the servlet configuration to be embedded in a war package. It can then be deployed in any standard application server
The declaration of all the graphql-java stuff
The DataFetchersDelegate interface declarations for all the Data Fetchers, which is the graphql-java word for GraphQL resolvers.
- The DataFetchersDelegate groups the Data Fetchers into one class per GraphQL object (including the Query and the Mutation)
- It contains the proper declarations to use the DataLoader out of the box
The POJOs to manipulate the GraphQL objects defined in the GraphQL schema.
- These POJOs are annotated with JPA annotations. This allows you to link them to almost any database
- You can customize these annotations, with the Schema Personalization file (see below for details)
All the necessary runtime is actually attached as source code into your project: the generated code is stand-alone. So, your project, when it runs, doesn't depend on any external dependency from graphql-java-generator.

Once all this is generated, your only work is to implement the DataFetchersDelegate interfaces. They are the link between the GraphQL schema and your data storage. As such, they are specific to your use case. A DataFetchersDelegate implementation looks like this:

package com.graphql_java_generator.samples.forum.server.specific_code;

[imports]

@Component
public class DataFetchersDelegateTopicImpl implements DataFetchersDelegateTopic {

	@Resource
	MemberRepository memberRepository;
	@Resource
	PostRepository postRepository;
	@Resource
	TopicRepository topicRepository;

	@Resource
	GraphQLUtil graphQLUtil;

	@Override
	public CompletableFuture<Member> author(DataFetchingEnvironment dataFetchingEnvironment,
			DataLoader<UUID, Member> dataLoader, Topic source) {
		return dataLoader.load(source.getAuthorId());
	}

	@Override
	public List<Post> posts(DataFetchingEnvironment dataFetchingEnvironment, Topic source, String since) {
		if (since == null)
			return graphQLUtil.iterableToList(postRepository.findByTopicId(source.getId()));
		else
			return graphQLUtil.iterableToList(postRepository.findByTopicIdAndSince(source.getId(), since));
	}

	@Override
	public List<Topic> batchLoader(List<UUID> keys) {
		return topicRepository.findByIds(keys);
	}
}

You'll find all the info on the server page.

Custom code templates

Customizing the templates allows you to modify the generated code, in the way you want.

So, if for any reason you may need to customize the generated code, you can replace the default templates by your own, by using the plugin parameter templates: the templates plugin parameter is a map where the key is the ID of the template to customize and the value is a classpath entry to the resources containing the customized template.

Customize templates shall be provided in a dependency configured in the plugin.

Both client and server templates can be customized.

All the documentation, and the list of available templates is available in the Customizing code templates page.