Custom GraphQL schema with graphql-java-annotations library

[GipHub123]

I recently upgraded my project to Spring Boot 3.5.0, which required removing graphql-java-kickstart and migrating to Spring GraphQL.
The existing GraphQL schema is quite complex, so manually defining the schema is not a viable option.

I've been having trouble getting the schema generated from annotations to work correctly.

a) Here I have test setup where schema is defined in resources (with default configuration).

resources/graphql/schema.gqls

type Query {
  hello: String
}

@Controller
@GraphQLName("LocationQuery")
public class LocationQueryV1 {

    @GraphQLField
    @QueryMapping
    public String hello() {
        return "Hello, world!";
    }

}

Request:

query LocationQuery {
  hello
}

Response:

{
  "data": {
    "hello": "Hello, world!"
  }
}

Schema fetched using Apollo Server

Indicates exactly one field must be supplied and this field must not be `null`.
"""
directive @oneOf on INPUT_OBJECT

"""Information about pagination in a connection."""
type PageInfo {
  """When paginating forwards, the cursor to continue."""
  endCursor: String

  """When paginating forwards, are there more items?"""
  hasNextPage: Boolean!

  """When paginating backwards, are there more items?"""
  hasPreviousPage: Boolean!

  """When paginating backwards, the cursor to continue."""
  startCursor: String
}

type Query {
  hello: String
}

So it work as expected.

**b) Here I have test setup where schema is defined using GraphQL annotations. Here I just add configuration and generate schema using annotations (no resources here) **

Configuration change

@Configuration
public class GraphQlConfig {

    @Bean
    public GraphQlSource source() {

        final GraphQLSchema graphQLSchema = GraphQLSchemaBuilder.build(LocationQueryV1.class);
        return GraphQlSource.builder(graphQLSchema).build();
    }
    
}

Schema fetched using Apollo Server

Indicates exactly one field must be supplied and this field must not be `null`.
"""
directive @oneOf on INPUT_OBJECT

"""Information about pagination in a connection."""
type PageInfo {
  """When paginating forwards, the cursor to continue."""
  endCursor: String

  """When paginating forwards, are there more items?"""
  hasNextPage: Boolean!

  """When paginating backwards, are there more items?"""
  hasPreviousPage: Boolean!

  """When paginating backwards, the cursor to continue."""
  startCursor: String
}

type Query {
  hello: String
}

Here schema should be identical with option a.

Request:

query LocationQuery {
  hello
}

Response:

ERROR 13-06-2025 19:59:22.700 [http-nio-9005-exec-1] o.s.g.e.ExceptionResolversExceptionHandler      - Unresolved NullPointerException for executionId 6b632ab8-6494-750b-0746-aa78deba5304
java.lang.NullPointerException: Cannot invoke "Object.getClass()" because "obj" is null
	at java.base/java.lang.reflect.Method.invoke(Method.java:572)
	at graphql.annotations.dataFetchers.MethodDataFetcher.get(MethodDataFetcher.java:87)
	at graphql.execution.ExecutionStrategy.invokeDataFetcher(ExecutionStrategy.java:510)
	at graphql.execution.ExecutionStrategy.fetchField(ExecutionStrategy.java:464)
	at graphql.execution.ExecutionStrategy.fetchField(ExecutionStrategy.java:404)
	at graphql.execution.ExecutionStrategy.resolveFieldWithInfo(ExecutionStrategy.java:363)
	at graphql.execution.ExecutionStrategy.getAsyncFieldValueInfo(ExecutionStrategy.java:328)

I'm not sure if my configuration is incorrect, and I’ve found it quite difficult to locate proper documentation or references on how this should be set up. I'm unsure whether this is a bug or if I'm doing something wrong.

Could someone please point me in the right direction?"

[bclozel]

Could you share a minimal sample so that we can have a look? There is a lot going on and it's hard to pinpoint why you're getting this NPE.
We don't provide a schema generation tool so I guess this is a custom tool you wrote?

[GipHub123]

@bclozel Not sure what I could provide more. I have been using this graphql-java-annotations

public class GraphQLSchemaBuilder {

    public static <T> GraphQLSchema build(final Class<T> clazz) {

        final GraphQLAnnotations graphQLAnnotations = GraphQLAnnotationsBuilder.build(clazz);

        final AnnotationsSchemaCreator.Builder builder = AnnotationsSchemaCreator
                .newAnnotationsSchema()
                .setAnnotationsProcessor(graphQLAnnotations)
                .query(clazz);

        final GraphQLSchema schema = builder.build();

        return Federation.transform(schema).build();
    }

}

As I see it, the schema is valid in both cases, but the end result differs. Spring Boot starts up without warnings in both scenarios.

Since the schema exposed to Apollo Server appears identical, my conclusion is that there must be something wrong with the setup.

[bclozel]

I was not the aware of this annotation processor. If you can share a minimal project, I can take a look and see where the problem is and even maybe check how we could help support this case, if possible.

[GipHub123]

I was assuming that this was a fairly standard solution for the code-first approach. 😄
I'll try to create sample projects for both cases within the next 1–3 days. It should be fairly straightforward. Thanks for your support!

[bclozel]

Cool, thanks! No rush on that.

To be clear, we don't support out of the box code first approaches in Spring for GraphQL. So it is very likely this approach will not work. But since it seems, there is a dedicated project for that, maybe we can help a bit.

[GipHub123]

@bclozel I spent quite a while looking for the right answer by browsing the Spring Boot source code.

package org.springframework.graphql.execution;

public interface GraphQlSource {

	/**
	 * Return a {@link GraphQlSource} builder that uses an externally prepared
	 * {@link GraphQLSchema}.
	 * @param schema the GraphQL schema
	 */
	static Builder<?> builder(GraphQLSchema schema) {
		return new ExternalSchemaGraphQlSourceBuilder(schema);
	}


}

From what I understand, the comment implies that it doesn’t matter how the GraphQL schema is generated — it can be downloaded, generated from annotations, or otherwise.

As I mentioned earlier, our real schema is quite complex. From my perspective, manually maintaining the schema is not an option — it would quickly become unmanageable.

[bclozel]

Understood. But if you generate the schema through an annotation processor we don't maintain and you manually register data fetchers - you're doing the bulk of the work and you might not need Spring GraphQL after all.

I suspect that other features are of interest to you and I'd like to know which parts you expect to be managed by Spring.