Auto-Generation

Instead of annotating every struct with @gqlType, auto-generation intelligently discovers and generates schemas for types that are referenced by your annotated types. This significantly reduces boilerplate while maintaining control over your public API surface.

Quick Start

Enable auto-generation in your configuration:

Example:

All three types are generated in the schema automatically.

Strategies

none - Manual Only

Only generate types with explicit @gqlType, @gqlInput, or @gqlInclude:

Use case: Full control, minimal schema, explicit API design

referenced - Smart Dependencies (Recommended)

Auto-generate types referenced by annotated types:

Example:

Generated types: User, UserProfile, Post

Not generated: UserSettings (exceeds max_depth)

all - Generate Everything

Auto-generate all structs found in scanned packages:

Use case: Quick prototyping, internal APIs, full codebase exposure

patterns - Pattern-Based Selection

Generate based on glob patterns:

Use case: Organized codebases with clear package structure

Max Depth Control

The max_depth setting controls how deep to traverse type dependencies:

Values:

• 0 - Unlimited depth (use with caution)
• 1 - Direct references only (recommended)
• 2 - Direct + transitive references
• 3+ - Further nesting

Example with depth: 1:

Example with depth: 2:

Include Options

Embedded Types

Auto-generate embedded struct types:

Field Types

Auto-generate types used in fields:

Excluding Types

Using @gqlIgnore

Prevent auto-generation of specific types:

Using Exclude Patterns

Exclude entire packages or patterns:

Out-of-Scope Types

Controls behavior when referenced types are not in scanned packages:

Options:

Example:

• warn: Generates User with Company field, shows warning
• fail: Stops generation with error
• ignore: Generates User silently
• exclude: Generates User without Company field

The @GqlInclude Directive

Mark types for inclusion without explicit type/input directives:

Use cases:

• Shared utility types
• Base types used across multiple schemas
• Types in external packages that should be included

Generic Type Handling

Auto-generation works with generic types and properly expands type parameters:

Generated:

See Generics Documentation for more details.

Best Practices

1. Start with referenced strategy: Provides good balance of automation and control
2. Use max_depth: 1: Prevents excessive schema generation
3. Leverage @gqlIgnore: Explicitly exclude internal/sensitive types
4. Use exclude_patterns: Filter entire package hierarchies
5. Review generated schemas: Ensure only intended types are public
6. Combine with explicit annotations: Annotate your API boundary, auto-generate internals

Configuration Reference

Once configured, run:

$ gqlschemagen generate

to generate schemas with auto-discovery enabled.