Getting Started with the Code Generator

This guide walks you through creating your first GraphQL API using the Code Generator with a simple "Hello World" example.

Prerequisites

• Java 11 or higher
• Basic understanding of GraphQL schemas

Step 1: Create Your Schema

Create a file hello.graphql with your GraphQL schema:

1
"""Root query type."""
2
type Query {
3
  """Say hello to someone."""
4
  hello(name: String!): String!
5
}

This minimal schema defines a single query that takes a name and returns a greeting.

Step 2: Run the Code Generator

You can run the code generator using the Builder API. Create HelloGraphQLCodeGenerator.java:

1
package com.example.codegen;
2

3
import com.psddev.graphql.schema.codegen.GraphQLCodeGenerator;
4

5
public class HelloWorldCodeGenerator {
6
    public static void main(String[] args) {
7
        new GraphQLCodeGenerator.Builder()
8
            .sdlPath("src/main/resources/hello.graphql")
9
            .generatedSourcesPackageName("com.example.generated")
10
            .generatedSourcesOutputDir("build/generated/graphql")
11
            .classNamePrefix("Hello")
12
            .templatedSourcesOutputDir("src/main/java")
13
            .templatedSourcesPackageName("com.example.graphql")
14
            .apiEndpointDisplayName("Hello API")
15
            .apiEndpointPath("/hello")
16
            .build()
17
            .generate();
18
    }
19
}

What Gets Generated

Running the generator creates generated sources in build/generated/graphql (regenerated on every run—don't edit these):

• HelloSchemaContext.java — abstract base class you'll extend with your business logic
• HelloQuery.java — abstract model class for your schema's Query type
• HelloQueryTypeGenerator.java — registers the type with the schema engine
• HelloSchemaLoader.java — loads your schema and discovers your context implementation
• HelloSealedClass.java, HelloSealedInterface.java, HelloSealedClassException.java, HelloUtil.java — sealing and utility support

It also scaffolds a templated source into src/main/java (written once, never overwritten—it's yours to edit):

• HelloEndpoint.java — the API endpoint serving your schema

Step 3: Implement the Schema Context

Create your implementation in src/main/java/com/example/graphql/HelloWorldSchemaContextImpl.java:

1
package com.example.graphql;
2

3
import com.example.generated.HelloQuery;
4
import com.example.generated.HelloSchemaContext;
5

6
public class HelloWorldSchemaContextImpl extends HelloSchemaContext {
7

8
    @Override
9
    public HelloQuery query() {
10
        return new HelloQuery() {
11
            @Override
12
            public String hello(String name) {
13
                return "Hello, " + name + "!";
14
            }
15
        };
16
    }
17
}

This is where you provide the actual business logic. The generated HelloSchemaLoader automatically discovers your concrete HelloSchemaContext implementation and calls your query() method to resolve GraphQL queries.

Step 4: Review the Endpoint

Because the generator was configured with a templatedSourcesOutputDir, it already scaffolded the endpoint that exposes your API—review and customize it as needed:

1
package com.example.graphql;
2

3
import java.util.Set;
4

5
import com.example.generated.HelloSchemaLoader;
6
import com.psddev.dari.db.Singleton;
7
import com.psddev.graphql.AbstractGraphQLApiEndpoint;
8
import com.psddev.graphql.GraphQLSchemaLoader;
9
import com.psddev.graphql.schema.GraphQLSchemaSettings;
10

11
@com.psddev.dari.db.Recordable.DisplayName("Hello API")
12
public final class HelloEndpoint extends AbstractGraphQLApiEndpoint implements Singleton {
13
    public static final String PATH = "/hello";
14

15
    @Override
16
    public Set<String> getPaths() {
17
        return Set.of(PATH);
18
    }
19

20
    @Override
21
    protected GraphQLSchemaLoader getSchemaLoader() {
22
        return new HelloSchemaLoader(GraphQLSchemaSettings.newBuilder()
23
            .build());
24
    }
25
}

Step 5: Test Your API

Start your application and test the endpoint with this query:

1
query {
2
  hello(name: "World")
3
}

Expected response:

1
{
2
  "data": {
3
    "hello": "Hello, World!"
4
  }
5
}

What You've Learned

You've successfully:

✅ Defined a GraphQL schema ✅ Generated type-safe Java code from the schema ✅ Implemented the business logic ✅ Exposed a working GraphQL API

Next Steps

• CLI Reference - Learn all code generator command-line options
• Gradle Integration - Integrate code generation into your build process
• Implementation Patterns - Best practices for implementing generated code
• Advanced Examples - Complex real-world scenarios