GraphQLJavaGen

Generate code for a specific GraphQL schema that provides query
builders and response classes.

Installation

The code generator requires ruby version 2.1 or later.

It is recommended to use bundler to install
the code generators ruby package.

Add this line to your application’s Gemfile:

gem 'graphql_java_gen'

And then execute:

$ bundle

The generated code depends on the com.shopify.graphql.support java
package. This can be added to a gradle project by adding the following
dependancy to you build.gradle file:

implementation 'com.shopify.graphql.support:support:0.2.1'

Usage

Monolith (single file) schema generation

Create a script that generates the code for a GraphQL API

require 'graphql_java_gen'
require 'graphql_schema'
require 'json'

introspection_result = File.read("graphql_schema.json")
schema = GraphQLSchema.new(JSON.parse(introspection_result))

GraphQLJavaGen.new(schema,
  package_name: "com.example.MyApp",
  nest_under: 'ExampleSchema',
  version: '2020-01',
  custom_scalars: [
    GraphQLJavaGen::Scalar.new(
      type_name: 'Decimal',
      java_type: 'BigDecimal',
      deserialize_expr: ->(expr) { "new BigDecimal(jsonAsString(#{expr}, key))" },
      imports: ['java.math.BigDecimal'],
    ),
  ]
).save("#{Dir.pwd}/../MyApp/src/main/java/com/example/MyApp/ExampleSchema.java")

The generated ExampleSchema.java will include a single class, ExampleSchema, which contains
all defined GraphQL schema entities as nested subclasses.

Granular (multiple file) schema generation

You may also generate separate class files for each schema entity using the save_granular command.
In this case, you should provide the path to a directory, not a single class.

e.g.

require 'graphql_java_gen'
require 'graphql_schema'
require 'json'

introspection_result = File.read("graphql_schema.json")
schema = GraphQLSchema.new(JSON.parse(introspection_result))

GraphQLJavaGen.new(schema,
  package_name: "com.example.MyApp",
  nest_under: 'ExampleSchema',
  version: '2020-01',
  custom_scalars: [
    GraphQLJavaGen::Scalar.new(
      type_name: 'Decimal',
      java_type: 'BigDecimal',
      deserialize_expr: ->(expr) { "new BigDecimal(jsonAsString(#{expr}, key))" },
      imports: ['java.math.BigDecimal'],
    ),
  ]
).save_granular("#{Dir.pwd}/../MyApp/src/main/java/com/example/MyApp/")

When using the granular option, the com.example.MyApp package will contain many small
class files each containing a single GraphQL schema entity.

Generated code

Regardless of whether you use the monolith or granular schema generator, the usage is largely the same.
The only difference depends on whether you access the schema entities directly from the provided package
or as nested, static classes on the ExampleSchema class.

That generated code depends on the com.shopify.graphql.support package.

The generated code includes a query builder that can be used to create a GraphQL
query in a type-safe manner.

String queryString = ExampleSchema.query(query -> query
    .user(user -> user
        .firstName()
        .lastName()
    )
).toString();

The generated code also includes response classes that will deserialize the response
and provide methods for accessing the field data with it already coerced to the
correct type.

ExampleSchema.QueryResponse response = ExampleSchema.QueryResponse.fromJson(responseJson);
if (!response.getErrors().isEmpty()) {
    for (Error error : response.getErrors()) {
        System.err.println("GraphQL error: " + error.message());
    }
}
if (data != null) {
    ExampleSchema.User user = data.getUser();
    System.out.println("user.firstName() + " " + user.lastName());
}

Lambda Expressions

The java 8 lambda expressions feature is essential for having a
nice syntax for the query builder. This feature is also available
for Android apps by using the
Jack toolchain.

If an older version of java must be used, then
retrolambda can be used
to backport this feature to java 5-7.

Development

After checking out the repo, run bundle to install ruby dependencies.
Then, run rake test to run the tests.

To install this gem onto your local machine, run bundle exec rake install or reference it from a Gemfile using the path option
(e.g. gem 'graphql_java_gen', path: '~/src/graphql_java_gen').

Contributing

See our contributing guidelines for more information.

License

The gem is available as open source under the terms of the
MIT License.