• What is it?
• Two main versions: 1.x and 2.x
• Availability: Maven and Gradle
  • Maven Plugin
  • Gradle Plugin
• The plugin goals/tasks
• The Documentation
• Compatibility with GraphQL
• Change log
• Note for contributors
• License

What is it?

The GraphQL Java Generator makes it easy to work in Java with graphQL in a schema first approach.

This project is a code generator, that allows to quickly develop GraphQL clients and GraphQL servers in java, based on a GraphQL schema.

That is: graphql-java-generator generates the boilerplate code, and lets you concentrate on what's specific to your use case.

• In client mode : graphql-java-generator generates an executor class for each query, mutation type and/or subscription type. These classes contain the methods to call the queries, mutations and subscriptions. That is: to call the GraphQL server, you just call the relevant method. In client mode, the plugin generates:
  • The POJOs from the GraphQL schema. That is: one class, interface or enum for each item in the provided GraphQL schema file(s)
  • The utility classes that allows you to execute queries, mutations and subscriptions, and to retrieve their result (including the GraphQL response's _extensions field)
  • Support blocking and (since 2.3) reactive (Mono, Flux) queries
  • The support for the full GraphQL specification (relay cursors, subscription, custom scalars, fragment, directive, GraphQL variables, GraphQL alias...).
  • The capability to use bind parameters within your queries, mutations and subscriptions, in an easier way than the GraphQL variables
  • It is based on Spring framework, and since 2.0 on spring-graphql. It still can be used with non-spring apps, as explained in the project's wiki.
  • When used in a spring boot app, each Spring component can be overridden. This allows fine tuning, like connecting to OAuth server, changing the WebClient, and much more
  • Since 1.17, it is possible to execute GraphQL request by just creating a Java interface, no code at all: GraphQL Repositories work almost like Spring Data Repositories. More information in the wiki
• In server mode : graphql-java-generator generates an almost ready to start GraphQL server. The developer has only to develop the access to the data. That is :
  • The generated code can be packaged either in a jar (starting as a Java application) or a war (starting in a Java container like tomcat or jetty).
  • graphql-java-generator generates the main method (in a jar project) or the main servlet class (in a war project),
  • It generates the POJOs for the provided GraphQL schema file(s).
  • It supports the full GraphQL specification (relay cursors, query/mutation/subscription, custom scalars, fragment, directive, aliases...)
  • The generated code is a Spring boot app (or servlet). You can override every default component, to personalize your server: GraphQL components (add instrumentation, type wiring, field wiring...), HTTP stuff (Spring Security, OAuth, OpenID Connect...) and much more. See the server FAQ for more information on this.
  • Various options allows to personalize the generated code (standard JPA annotations, Java type for ID fields, custom scalars, specific annotations...). See the plugin parameters page for all the goal/tasks and their plugin parameters
  • The developer just has to implement each DataFetchersDelegate, based on the provided interfaces, to provide the access to the data

Other points that are worth to point out:

• The project is extensively tested:
  • Through unit tests (for the runtime),
  • Through unit and integration tests (for the plugin logic)
  • Through full integration tests: three samples contain both the client and the server parts. Integration tests are run on client side, against "its" server side. More than 250 integration tests are run on client side against the server part.
• A big effort is done to avoid any impact on your code, when the plugin evolves.
• A maven/gradle goal/task allows to merge several schemas in one, adding (for instance) relay capability in the generated schema

Two main versions: 1.x and 2.x

The 1.x version:

• Allows non-spring application either by using the javax.ws.rs.client.Client client, which is deprecated and has been removed in Spring Boot 3
• Is based directly on graphql-java, and a clone of graphql-java-spring.
• Is not compatible with Spring Boot 3 and Spring Framework 5

The 2.x version:

• Is based on spring-graphql
• Is compatible with Spring Boot 3 and Spring Framework 6
  • Another version of the Gradle plugin had been created to achieve this (see below)
• (since 2.3) Allows also reactive queries (that returns reactive Mono or Flux)
• Please check the Client migration from 1.x to 2.x or Server migration from 1.x to 2.x if you're using the 1.x version.

Availability: Maven and Gradle

The generator is currently available both as a Maven plugin and as a Gradle plugins.

The plugin documentation is available on this page. It lists all the plugin goals and their parameters. It is valid for both Maven and Gradle.

Maven plugin

The Maven plugin is available in the project (graphql-maven-plugin-project).

The last published version can be found in the Maven Central Repository

Gradle Plugin

Two Gradle plugins are available from the project graphql-gradle-plugin-project.

They offer the exact same functionalities:

• graphql-gradle-plugin is compiled against Spring Boot 2 and Spring Framework 5
• graphql-gradle-plugin3 is compiled against Spring Boot 3 and Spring Framework 6

The plugin goals/tasks

All maven goals and gradle tasks are described on this page

This plugin contains these goals (Maven) / tasks (Gradle):

• generateClientCode : this goal generates the client code from the Graphql schema file(s)
  • You'll find all the details on this page
• generateServerCode : this goal generates the server code from the Graphql schema file(s)
  • You'll find all the details on this page
• generatePojo : this goal generates only the java objects that match the provided GraphQL schema. It allows to work in Java with graphQL, in a schema first approach.
  • You'll find all the details on this page
• (deprecated) graphql was the previous main goal. It can generate both the client and the server code, thanks to its mode parameter.
  • You'll find all the details on this page
• merge allows to generate a GraphQL schema file, based on the source GraphQL schemas. It can be used to merge several GraphQL schema files into one file, or to reformat the schema files.
  • You'll find all the details on this page

The Documentation

The full documentation is available on the github wiki.

You can also:

• Take a look at the tutorials :
  • For Maven *GraphQL-Forum-Maven-Tutorial-client
    • GraphQL-Forum-Maven-Tutorial-server
  • For Gradle
    • GraphQL-Forum-Gradle-Tutorial-client
    • GraphQL-Forum-Gradle-Tutorial-server
• Study the samples available in the project
• Directly go to the client or server documentation on the github wiki

Compatibility with GraphQL

This plugin respects all the GraphQL specifications:

• queries, mutations and subscriptions
• introspection
• custom scalars
• input types
• interfaces and unions (that are both implemented in Java interfaces into the generated code)
• directives
• fragments (global and inline)
• input parameters (for fields and directives)
• Use of Bind Parameters to map Java variables with input parameters
• easy execution of just a query/mutation/subscription (one field of the query, mutation or subscription type) as a standard method call
• execution of a full GraphQL request, which allows to execute several queries or several mutations at once
• Management of the GraphQL response's extensions field
• Comments and description coming from the GraphQL schema are reported in the generated code

Change log

The Change Log is available here

Note for contributors

Branches

Since 01 may 2023, the default branch is the master_2.x branch. It contains all the changes done for the 2.0 version. This branch

The historical branch has been renamed from master to master_1.x branch. This branch is used only for the 1.x maintenance, that is: only major and security issues.

Project organization

All the plugin logic is stored in the graphql-maven-plugin-project project.

The Maven plugin and the Gradle plugin are just wrapper for the plugin logic, available in the graphql-maven-plugin-logic module of the maven project.

If you want to compile the maven project, you'll have to add the lombok.jar file in your IDE. Please see the relevant section, in the Install menu of the https://projectlombok.org/ home page. This very nice tools generates all java boiler plate code, like setters, getters, constructors from fields...

If you use eclipse, please use the code formatter given with the project (file graphql-java-generator (eclipse code formatter).xml at the root of the project). This allows to have the sample code formatting: the code is then homogeneous, and the comparison between versions is simpler. To do this, go to the eclipse preferences, select Java/Code Style/Formatter, and import this file. Then, in the Java/Editor/Save Actions, check the "Perform the selected action on save", "Format source code", "Format all lines", "Organize imports" and "Additional actions" which its default content

License

graphql-java-generator is licensed under the MIT License. See LICENSE for details.