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)
- 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 can be used within a spring boot app, or in non-spring apps. When using as 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 part, and integration tests are run on client side, against "its" server side. Around 150 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
The 2.x version: About to be released (TODO: update this when 2.x is released)
- Is based on spring-graphql
- Is compatible with Spring Boot 3
- Almost compatible with projects based on the versions 1.x of this plugin
Availability: Maven and Gradle
The generator is currently available both as a Maven plugin and as a Gradle plugin:
The plugin documentation, generated by maven, is available on this page. It lists all the plugin goals and their parameters. It is valid for both Maven and Gradle.
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)
generateServerCode : this goal generates the server code from the Graphql schema file(s)
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.
- (deprecated)
graphql was the previous main goal. It can generate both the client and the server code, thanks to its mode parameter.
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.
The Documentation
The full documentation is available on the github wiki.
You can also:
- Take a look at the tutorials
- Study the samples
- Directly go to the client or server documentation
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
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.