MetaEngine GraphQL Java Spring

Generate Java Spring GraphQL service clients and models from a GraphQL schema.

A Maven plugin that produces typed Spring RestClient query / mutation / subscription clients and model records from a GraphQL schema (SDL) — with built-in authentication, retries, timeouts, and error handling, straight into your build at generate-sources.

---

Quick Links

• Maven Central: eu.metaengine:metaengine-graphql-java-spring-maven-plugin
• NuGet Package: MetaEngine.Java.GraphQL.Spring
• Website: metaengine.eu

---

Features

• ✅ Spring RestClient - Typed GraphQL clients with base-URL injection via a Spring property
• ✅ Operations - Query, Mutation, and Subscription clients generated from your schema
• ✅ Authentication - Bearer token, basic auth, and custom headers from environment variables
• ✅ Retries - Exponential-backoff retries with a configurable max attempt count
• ✅ Timeouts - Single timeout, or split connect / read timeouts
• ✅ Error Handling - Smart error handling on the HTTP client
• ✅ JavaDoc - Optional doc-comment generation from GraphQL schema descriptions
• ✅ Fragments - Reusable named fragments for object-type selections
• ✅ OneOf Inputs - @oneOf tagged-union inputs become sealed interfaces
• ✅ Options Object - Collapse long parameter lists into an options object past a threshold

---

Requirements

• JDK 11 or later
• Maven 3.6 or later
• .NET 8.0 runtime (Download) — the plugin runs the bundled MetaEngine generator via dotnet, so the runtime must be on your PATH

---

Quick Start

Add the plugin to your pom.xml and bind it to the generate-sources phase:

<build>
  <plugins>
    <plugin>
      <groupId>eu.metaengine</groupId>
      <artifactId>metaengine-graphql-java-spring-maven-plugin</artifactId>
      <version>1.0.0</version>
      <executions>
        <execution>
          <goals><goal>generate</goal></goals>
          <configuration>
            <inputSpec>src/main/resources/schema.graphql</inputSpec>
            <packageName>com.example.api</packageName>
            <documentation>true</documentation>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Then generate (the output is added to your compile source roots automatically):

mvn generate-sources

The plugin can also be run directly without a lifecycle binding:

mvn eu.metaengine:metaengine-graphql-java-spring-maven-plugin:generate \
  -Dmetaengine.inputSpec=src/main/resources/schema.graphql \
  -Dmetaengine.packageName=com.example.api

---

Configuration Options

Every option is a <configuration> element, also settable on the command line via its metaengine.* property.

Element	Property	Description	Default
inputSpec (required)	metaengine.inputSpec	GraphQL schema (SDL) file path or URL	-
packageName (required)	metaengine.packageName	Java package for generated code	-
outputDirectory	metaengine.outputDirectory	Output directory	${project.build.directory}/generated-sources/metaengine
baseUrlProperty	metaengine.baseUrlProperty	Spring property name for base-URL injection	api.base-url
documentation	metaengine.documentation	Generate JavaDoc comments	false
bearerAuth	metaengine.bearerAuth	Env var name holding the bearer token	-
bearerAuthHeader	metaengine.bearerAuthHeader	Custom header name for bearer auth	Authorization
basicAuth	metaengine.basicAuth	Env var names for basic auth (USER_VAR,PASS_VAR)	-
customHeaders	metaengine.customHeaders	Custom headers from env vars (Header-Name:ENV_VAR, repeatable)	-
timeout	metaengine.timeout	Request timeout in seconds (connect + read)	-
timeoutConnect	metaengine.timeoutConnect	Connect timeout in seconds	-
timeoutRead	metaengine.timeoutRead	Read timeout in seconds	-
retry	metaengine.retry	Enable retries with exponential backoff (max attempts)	3 when enabled
errorHandling	metaengine.errorHandling	Enable smart error handling on the HTTP client	false
optionsThreshold	metaengine.optionsThreshold	Parameter count that triggers the options-object pattern	4
fragments	metaengine.fragments	Emit reusable named fragments for object-type selections	false
oneOfInputs	metaengine.oneOfInputs	Generate idiomatic @oneOf tagged-union input types	false
clean	metaengine.clean	Clean the output directory before generation	false
verbose	metaengine.verbose	Enable verbose logging	false

---

Production-Ready Configuration

<configuration>
  <inputSpec>src/main/resources/schema.graphql</inputSpec>
  <packageName>com.example.api</packageName>
  <documentation>true</documentation>
  <fragments>true</fragments>

  <!-- Auth from environment variables -->
  <bearerAuth>API_TOKEN</bearerAuth>

  <!-- Resilience -->
  <timeout>30</timeout>
  <retry>3</retry>
  <errorHandling>true</errorHandling>
</configuration>

Authentication values are read from environment variables at runtime — secrets never end up in your generated source or your pom.xml.

---

Generated Code Structure

target/generated-sources/metaengine/
  ├── client/        # Spring @Service GraphQL clients (package <your.package>.client)
  │   ├── QueryClient.java
  │   ├── MutationClient.java
  │   ├── SubscriptionClient.java
  │   ├── BaseGraphQlClient.java
  │   └── GraphQLFragments.java       # generated with fragments
  └── model/         # Java records, one per GraphQL type (package <your.package>.model)
      ├── User.java
      ├── Post.java
      ├── PostFilter.java             # @oneOf input → sealed interface
      ├── Scalars.java
      └── ...

Clients are Spring @Service components — inject them directly into your beans. The base URL is bound to the baseUrlProperty (default api.base-url) from your Spring configuration. Subscription clients additionally read the GraphQL WebSocket endpoint from the api.graphql-ws-url property.

---

Support

• Issues: GitHub Issues
• Email: info@metaengine.eu
• Website: metaengine.eu

---

License

MIT License - see LICENSE file for details.

---

About This Repository

This is the documentation and issue tracking repository for MetaEngine GraphQL Java Spring. The plugin is published to Maven Central.

Source code is proprietary, but the plugin is free to use under the MIT license.