View full coverage report

graphqlcodegen-maven-plugin

This maven plugin is a port of the netflix codegen plugin for Gradle. Found here.

Architecture

This project is organized as a single Maven module at the repository root:

graphqlcodegen-maven-plugin

This is the Maven plugin that users apply to their projects. It provides goals for generating Java (or Kotlin) code from GraphQL schemas, mirroring the functionality of the Netflix DGS Gradle codegen plugin. It is responsible for:

• Accepting configuration via plugin parameters.
• Resolving schema files from the local project and dependencies.
• Invoking the DGS codegen library with the correct configuration.
• Managing incremental code generation and manifest tracking.
• Holding a checked-in CodeGenConfigBuilder (src/main/java/io/github/deweyjose/graphqlcodegen) that mirrors the upstream CodeGenConfig constructor shape.

Contributing

GitHub Issue

Feel free to simply create a GitHub issue for requests to integrate with newer releases of the core DGS Codegen library.

PRs

PRs are welcome as well. The level of difficulty across DGS Codegen updates varies. Typically, new plugin options are added when the CodeGenConfig constructor in the core library changes.

When constructor parameters change upstream:

• Update CodeGenConfigBuilder to match the latest constructor shape and ordering.
• Wire new options through:
  • src/main/java/io/github/deweyjose/graphqlcodegen/Codegen.java
  • src/main/java/io/github/deweyjose/graphqlcodegen/CodegenConfigProvider.java
  • src/main/java/io/github/deweyjose/graphqlcodegen/CodegenExecutor.java
• Add/update tests and document options in this README.

Process:

1. Bump the version in pom.xml
2. Run mvn spotless:apply clean install locally to ensure the project still builds and is formatted
3. Adjust Codegen and related classes to support new options if needed
4. Test with the example project:
   • Clone graphqlcodegen-example
   • Bump the plugin version in its pom.xml to match your changes
   • Run mvn spotless:apply clean install in the example project to ensure everything works as expected

Note: In the future, the example repo will be folded into this repository as a set of test modules to make testing and validation even easier.

Overview

The DGS Code Generation plugin generates code for basic types and example data fetchers based on your Domain Graph Service's graphql schema file during the project's build process. The plugin requires the designated packageName for file generation. If no schemaPath is specified, it will look in the src/main/resources/schema folder for any files with .graphqls, .graphql or .gqls extension.

Example Repo

https://github.com/deweyjose/graphqlcodegen-example

Options

Options are configured in the <configuration> element of the dgs-codegen-maven-plugin plugin.

onlyGenerateChanged

This options enables the plugin to limit code generation to only schema files that have changed. Today this only works with schemaPaths.

This only works for <schemaPaths>. A subsequent release for schema compilation via dependencies will be release soon.

• Type: boolean
• Required: false
• Default: true

<onlyGenerateChanged>true</onlyGenerateChanged>

subPackageNameDocs

• Type: string
• Required: false
• Default: docs

Example

<subPackageNameDocs>docs</subPackageNameDocs>

generateDocs

• Type: string
• Required: false
• Default: docs

Example

<generateDocs>true</generateDocs>

generatedDocsFolder

• Type: string
• Required: false
• Default: ./generated-docs

Example

<generatedDocsFolder>true</generatedDocsFolder>

addGeneratedAnnotation

• Type: boolean
• Required: false
• Default: false

Example

<addGeneratedAnnotation>true</addGeneratedAnnotation>

skip

• Type: boolean
• Required: false
• Default: false

Example

<dgs.codegen.skip>true</dgs.codegen.skip>

Or

# mvn ... -Ddgs.codegen.skip=true

schemaPaths

A list of schema file or directory paths.

Directory paths: Only files with file extensions .graphql, .graphqls and .gqls will be considered.

Default value is ${project.basedir}/src/main/resources/schema.

• Type: array
• Required: false
• Default: ${project.basedir}/src/main/resources/schema

Example

<schemaPaths>
  <param>src/main/resources/schema/schema.graphqls1</param>
  <param>src/main/resources/schema/schema.graphqls2</param>
  <param>src/main/resources/someDirWithSchema</param>
</schemaPaths>

schemaJarFilesFromDependencies

• Type: array
• Required: false
• Default: []
• Official doc : https://netflix.github.io/dgs/generating-code-from-schema/#generating-code-from-external-schemas-in-jars.
• Please note that .graphql(s) files must exist under the META-INF folder in the external jar file.

Example

<schemaJarFilesFromDependencies>
  <param>com.netflix.graphql.dgs:some-dependency:1.0.0</param>
  <param>com.netflix.graphql.dgs:some-dependency:X.X.X</param>
</schemaJarFilesFromDependencies>

packageName

• Type: string
• Required: true

Example

<packageName>com.acme.se.generated</packageName>

typeMapping

• Type: map
• Required: false

Example

<typeMapping>
  <Date>java.time.LocalDateTime</Date>
</typeMapping>

typeMappingPropertiesFiles

Specifies one or more typeMapping properties files that are available as compile-time classpath resources from external dependencies (e.g., shared JARs).

Each properties file must contain key-value pairs that will be added to the typeMapping map only if a mapping for a given GraphQL type is not already present.

If the same GraphQL type appears in both the typeMapping configuration and one of the typeMappingPropertiesFiles, the value from typeMapping will take precedence, and the entry from the properties file will be ignored.

• Type: Array
• Required: No

Example (XML)

<typeMappingPropertiesFiles>
  <typeMappingPropertiesFile>commontypes-typeMapping.properties</typeMappingPropertiesFile>
  <typeMappingPropertiesFile>someother-commontypes-typeMapping.properties</typeMappingPropertiesFile>
</typeMappingPropertiesFiles>

localTypeMappingPropertiesFiles

Specifies one or more typeMapping properties files that are available in the local project directory. These files should be specified relative to the project root.

Each properties file must contain key-value pairs that will be added to the typeMapping map only if a mapping for a given GraphQL type is not already present.

If the same GraphQL type appears in both the typeMapping configuration and one of the localTypeMappingPropertiesFiles, the value from typeMapping will take precedence, and the entry from the properties file will be ignored.

• Type: Array
• Required: No

Example (XML)

<localTypeMappingPropertiesFiles>
  <localTypeMappingPropertiesFile>src/main/resources/type-mapping.properties</localTypeMappingPropertiesFile>
</localTypeMappingPropertiesFiles>

subPackageNameClient

• Type: string
• Required: false
• Default: client

Example

<subPackageNameClient>client</subPackageNameClient>

subPackageNameDatafetchers

• Type: string
• Required: false
• Default: client

Example

<subPackageNameDatafetchers>datafetchers</subPackageNameDatafetchers>

subPackageNameTypes

• Type: string
• Required: false
• Default: client

Example

<subPackageNameTypes>types</subPackageNameTypes>

generateBoxedTypes

• Type: boolean
• Required: false
• Default: false

Example

<generateBoxedTypes>false</generateBoxedTypes>

generateClientApi

• Type: boolean
• Required: false
• Default: false

Example

<generateClientApi>false</generateClientApi>

generateClientApiv2

• Type: boolean
• Required: false
• Default: false

Example

<generateClientApiv2>false</generateClientApiv2>

generateInterfaces

• Type: boolean
• Required: false
• Default: false

Example

<generateInterfaces>false</generateInterfaces>

generateKotlinNullableClasses

• Type: boolean
• Required: false
• Default: false

Example

<generateKotlinNullableClasses>false</generateKotlinNullableClasses>

generateKotlinClosureProjections

• Type: boolean
• Required: false
• Default: false

Example

<generateKotlinClosureProjections>false</generateKotlinClosureProjections>

outputDir

• Type: string
• Required: false
• Default: ${project.build.directory}/generated-sources

Example:

<outputDir>${project.build.directory}/generated-sources</outputDir>

autoAddSource

Controls whether the plugin automatically adds the generated sources directory to the Maven compile classpath. This eliminates the need for the build-helper-maven-plugin in most setups.

• Type: boolean
• Required: false
• Default: true

Example:

<autoAddSource>true</autoAddSource>

exampleOutputDir

• Type: string
• Required: false
• Default: ${project.build.directory}/generated-examples

Example:

<exampleOutputDir>${project.build.directory}/generated-examples</exampleOutputDir>

schemaManifestOutputDir

• Type: string
• Required: false
• Default: ${project.build.directory}/graphqlcodegen

Example:

<schemaManifestOutputDir>${project.build.directory}/graphqlcodegen</schemaManifestOutputDir>

includeQueries

• Descripti