GraphQL code generator

A Maven plugin that generates Java types and data fetcher interfaces for a GraphQL API from its schema.

Requirements

Java 25 or newer and Maven 3.9.0 or newer.

Usage

The generate goal runs in the generate-sources phase. It writes the code to target/generated-sources/graphql and adds that directory as a source root, so no other plugins are needed.

A file is only rewritten when its content changes, so an unchanged schema does not force a recompile. The generated members follow the schema order. The code is not formatted for readability.

<plugin>
  <groupId>org.opentripplanner</groupId>
  <artifactId>graphql-codegen</artifactId>
  <version>${graphql-codegen.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <configFile>${project.basedir}/src/build/graphql-codegen.yml</configFile>
      </configuration>
    </execution>
  </executions>
</plugin>

Parameter	Property	Default
configFile	graphql-codegen.configFile	required
outputDirectory	graphql-codegen.outputDirectory	${project.build.directory}/generated-sources/graphql
skip	graphql-codegen.skip	false

In a project that declares the plugin, you can also run it on its own with mvn graphql-codegen:generate.

For a real-world example, see the GTFS GraphQL API in OpenTripPlanner: the application/pom.xml and application/src/build/gtfs-graphql-codegen.yml files.

The generated code depends on graphql-java (for example graphql.schema.DataFetcher), so the consuming project must have it on its compile classpath.

Configuration

schema: path/to/schema.graphqls # relative to the config file

generates:
  # One entry per generated file, named <className>.java
  MyTypes.java:
    plugins:
      - java # enums, input classes and <Type><Field>Args classes
    config:
      className: MyTypes
      listType: List
  MyDataFetchers.java:
    plugins:
      - java-resolvers # DataFetcher interfaces for object types
    config:
      className: MyDataFetchers

# Shared config; a per-file config overrides these keys
config:
  package: org.example.generated
  typesPrefix: GraphQL
  scalars:
    Duration: java.time.Duration
  mappers:
    Stop: org.example.model.Stop#Stop

• scalars: maps a GraphQL scalar to a Java type. Unmapped custom scalars become Object.
• mappers: maps a GraphQL type to a Java type. Use fully.qualified.Import#TypeExpression to import a class and use a (possibly generic) type expression, for example graphql.relay.Edge#Edge<TransitAlert>. Unmapped types become Object.
• listType: the Java type used for GraphQL lists (default Iterable).
• typesPrefix: a prefix for all generated type names (default none).
• className: the name of the generated outer class. It must match the output file name.

Building

mvn verify

The build formats the code with Spotless and Prettier, so node and npm must be on the PATH. Use -Dplugin.spotless.goal=check to only check the formatting, or -Dplugin.spotless.skip to skip it.

The integration tests in src/it build sample projects with the plugin, using maven-invoker-plugin. Use -Dinvoker.skip to skip them.

The artifacts are signed with GPG in the verify phase. Use -Dgpg.skip if you don't have the signing key.

Releasing

make release

License

MIT. The design and configuration format are based on GraphQL Code Generator and its java plugins, which are also MIT-licensed. See the LICENSE file for details.