Java configuration options

This section details the available configuration options for the Java SDK. All configuration is managed in the gen.yaml file under the java section.

Identity and publishing


java:
  version: 1.2.3
  templateVersion: v2
  projectName: "openapi"
  groupID: "com.mycompany"
  artifactID: "my-sdk"
  packageName: "com.mycompany.sdk"
  ossrhURL: "https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/"
  githubURL: "https://github.com/mycompany/my-sdk"
  companyName: "My Company"
  companyURL: "https://www.mycompany.com"
  companyEmail: "support@mycompany.com"
  description: "SDK enabling Java developers to easily integrate with the MyCompany API."
  license:
    name: "The MIT License (MIT)"
    url: "https://mit-license.org/"
    shortName: "MIT"

Name

version

Required

true

Description

The current version of the SDK.

Default Value

0.0.1

templateVersion

Required

false

Description

The template version to use. Must be

Default Value

projectName

Required

true

Description

Assigns Gradle

, which gives a name to the Gradle build. See Gradle Naming .

Default Value

openapi

groupID

Required

true

Description

The groupID to use for namespacing the package. This is usually the reversed domain name of the organization. If publishing is enabled, it will also be used as the artifact's groupId (e.g.

Default Value

org.openapis

artifactID

Required

true

Description

The artifactID is used as the final simple name in the base package if

is not specified. This is usually the name of the project. If publishing is enabled, it will also be used as the artifactId (e.g.

Default Value

openapi

packageName

Required

false

Description

The base package name for generated classes. If not present,

will be used.

Default Value

ossrhURL

Required

false

Description

The URL of the staging repository to publish the SDK artifact to.

Default Value

N/A

githubURL

Required

for publishing

Description

The GitHub URL where the artifact is hosted. Sets metadata required by Maven.

Default Value

github.com/owner/repo

companyName

Required

for publishing

Description

The name of the company. Sets metadata required by Maven.

Default Value

My Company

companyURL

Required

for publishing

Description

The company homepage URL. Sets metadata required by Maven.

Default Value

www.mycompany.com

companyEmail

Required

for publishing

Description

A support email address for the company. Sets metadata required by Maven.

Default Value

info@mycompany.com

description

Required

false

Description

The description to use in the Maven POM file.

Default Value

SDK enabling Java developers to easily integrate with the {CompanyName} API.

license

Required

false

Description

License information. Defaults to the MIT license if not otherwise specified.

Default Value

MIT License

Name	Required	Default Value	Description
version	true	0.0.1	The current version of the SDK.
templateVersion	false	v2	The template version to use. Must be .
projectName	true	openapi	Assigns Gradle , which gives a name to the Gradle build. See Gradle Naming .
groupID	true	org.openapis	The groupID to use for namespacing the package. This is usually the reversed domain name of the organization. If publishing is enabled, it will also be used as the artifact's groupId (e.g. ).
artifactID	true	openapi	The artifactID is used as the final simple name in the base package if is not specified. This is usually the name of the project. If publishing is enabled, it will also be used as the artifactId (e.g. ).
packageName	false		The base package name for generated classes. If not present, will be used.
ossrhURL	false	N/A	The URL of the staging repository to publish the SDK artifact to.
githubURL	for publishing	github.com/owner/repo	The GitHub URL where the artifact is hosted. Sets metadata required by Maven.
companyName	for publishing	My Company	The name of the company. Sets metadata required by Maven.
companyURL	for publishing	www.mycompany.com	The company homepage URL. Sets metadata required by Maven.
companyEmail	for publishing	info@mycompany.com	A support email address for the company. Sets metadata required by Maven.
description	false	SDK enabling Java developers to easily integrate with the {CompanyName} API.	The description to use in the Maven POM file.
license	false	MIT License	License information. Defaults to the MIT license if not otherwise specified.

Build and language


java:
  languageVersion: 11
  additionalDependencies:
    - "implementation:com.fasterxml.jackson.core:jackson-databind:2.16.2"
    - "testImplementation:junit:junit:4.13.2"
  additionalPlugins:
    - 'id("org.jetbrains.kotlin.jvm") version "1.9.0"'
  generateSpringBootStarter: true
  enableFormatting: false

Name

languageVersion

Required

false

Description

The Java version for the generated SDK (11-21). This will be used to set the source and target compatibility in the Gradle build file.

Default Value

additionalDependencies

Required

false

Description

Additional dependencies to include in

. Format: an array of

strings.

Default Value

[]

additionalPlugins

Required

false

Description

Additional plugins to include in

. Format: an array of strings, e.g.

Default Value

[]

generateSpringBootStarter

Required

false

Description

Generate Spring Boot starters for the Java SDK.

Default Value

true

enableFormatting

Required

false

Description

Enable automatic code formatting for generated Java files using dprint.

Default Value

false

Name	Required	Default Value	Description
languageVersion	false	11	The Java version for the generated SDK (11-21). This will be used to set the source and target compatibility in the Gradle build file.
additionalDependencies	false	[]	Additional dependencies to include in . Format: an array of strings.
additionalPlugins	false	[]	Additional plugins to include in . Format: an array of strings, e.g. .
generateSpringBootStarter	false	true	Generate Spring Boot starters for the Java SDK.
enableFormatting	false	false	Enable automatic code formatting for generated Java files using dprint.

API surface shape


java:
  maxMethodParams: 4
  flattenGlobalSecurity: true
  operationScopedParams: true
  respectTitlesForPrimitiveUnionMembers: true
  imports:
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks

Name

maxMethodParams

Required

false

Description

The maximum number of parameters a method can have before the resulting SDK endpoint is no longer "flattened" and an input object is created instead.

will use input objects always.

Default Value

flattenGlobalSecurity

Required

false

Description

Flatten the global security configuration if there is only a single option in the spec.

Default Value

on for new SDKs

operationScopedParams

Required

false

Description

When falling back to global parameters, only applies those declared at the operation level.

Default Value

true

imports

Required

false

Description

Configuration for model import structure (folder layout for

Default Value

{}

respectTitlesForPrimitiveUnionMembers

Required

false

Description

Use title or

for primitive union member field names instead of type-based defaults.

Default Value

on for new SDKs

Name	Required	Default Value	Description
maxMethodParams	false	4	The maximum number of parameters a method can have before the resulting SDK endpoint is no longer "flattened" and an input object is created instead. will use input objects always.
flattenGlobalSecurity	false	on for new SDKs	Flatten the global security configuration if there is only a single option in the spec.
operationScopedParams	false	true	When falling back to global parameters, only applies those declared at the operation level.
imports	false	{}	Configuration for model import structure (folder layout for / / / / ).
respectTitlesForPrimitiveUnionMembers	false	on for new SDKs	Use title or for primitive union member field names instead of type-based defaults.

Import paths

Component

callbacks

Default Value

models/callbacks

Description

The directory where callback models will be imported from.

errors

Default Value

models/errors

Description

The directory where error models will be imported from.

operations

Default Value

models/operations

Description

The directory where operation models (i.e., API endpoints) will be imported from.

shared

Default Value

models/components

Description

The directory for shared components, such as reusable schemas and data models, imported from the OpenAPI spec.

webhooks

Default Value

models/webhooks

Description

The directory for webhook models, if the SDK includes support for webhooks.

Component	Default Value	Description
callbacks	models/callbacks	The directory where callback models will be imported from.
errors	models/errors	The directory where error models will be imported from.
operations	models/operations	The directory where operation models (i.e., API endpoints) will be imported from.
shared	models/components	The directory for shared components, such as reusable schemas and data models, imported from the OpenAPI spec.
webhooks	models/webhooks	The directory for webhook models, if the SDK includes support for webhooks.

Errors


java:
  clientServerStatusCodesAsErrors: true
  defaultErrorName: "APIException"
  baseErrorName: ""

Name

clientServerStatusCodesAsErrors

Required

false

Description

Whether to treat 4xx and 5xx status codes as errors.

Default Value

true

defaultErrorName

Required

false

Description

The name of the default exception that is thrown when an API error occurs.

Default Value

(new) /

(legacy)

baseErrorName

Required

false

Description

The name of the base error class used for HTTP error responses.

Default Value

N/A

Name	Required	Default Value	Description
clientServerStatusCodesAsErrors	false	true	Whether to treat 4xx and 5xx status codes as errors.
defaultErrorName	false	(new) / (legacy)	The name of the default exception that is thrown when an API error occurs.
baseErrorName	false	N/A	The name of the base error class used for HTTP error responses.

Async and streaming


java:
  asyncMode: "enabled"
  prefixModeMethodNames: true
  nullFriendlyParameters: true
  enableStreamingUploads: true
  multipartArrayFormat: "standard"

Name

asyncMode

Required

false

Description

Whether to generate reactive/async API methods that use non-blocking operations. Values:

Default Value

auto (

for new SDKs and SDKs without registered hooks)

prefixModeMethodNames

Required

false

Description

Use

prefix for sync/async mode-switching methods (

) instead of bare names. Follows RxJava/Mutiny conventions and avoids collisions with SubSDK accessor names.

Default Value

on for new SDKs

nullFriendlyParameters

Required

false

Description

Whether to use null-friendly parameters.

Default Value

on for new SDKs

enableStreamingUploads

Required

false

Description

Whether to enable streaming uploads for sync SDKs, allowing users to pass various stream-oriented types (e.g. Blob) for bytes fields instead of byte arrays.

Default Value

on for new SDKs (auto-on if

)

multipartArrayFormat

Required

false

Description

Format for array field names in multipart form data.

appends

to array field names (e.g.,

uses the field name as-is. Set to

for correct multipart/form-data handling.

Default Value

(new) /

(existing)

Name	Required	Default Value	Description
asyncMode	false	auto ( for new SDKs and SDKs without registered hooks)	Whether to generate reactive/async API methods that use non-blocking operations. Values: or .
prefixModeMethodNames	false	on for new SDKs	Use prefix for sync/async mode-switching methods ( / ) instead of bare names. Follows RxJava/Mutiny conventions and avoids collisions with SubSDK accessor names.
nullFriendlyParameters	false	on for new SDKs	Whether to use null-friendly parameters.
enableStreamingUploads	false	on for new SDKs (auto-on if )	Whether to enable streaming uploads for sync SDKs, allowing users to pass various stream-oriented types (e.g. Blob) for bytes fields instead of byte arrays.
multipartArrayFormat	false	(new) / (existing)	Format for array field names in multipart form data. appends to array field names (e.g., ). uses the field name as-is. Set to for correct multipart/form-data handling.

Unions and enums


java:
  unionStrategy: "populated-fields"
  forwardCompatibleUnionsByDefault: true
  forwardCompatibleEnumsByDefault: true
  generateOptionalUnionAccessors: true
  generateUnionDocs: true
  inferUnionDiscriminators: true

Name

unionStrategy

Required

false

Description

Strategy for deserializing union types.

tries each type in order and returns the first valid match.

uses sophisticated candidate scoring based on mapped fields, enum fields, and JSON size to select the best matching union member.

Default Value

populated-fields

forwardCompatibleUnionsByDefault

Required

false

Description

Enable forward compatibility for unions in responses. When true, unions are open to unknown values with raw JSON fallback. Individual unions can be controlled with

Default Value

on for new SDKs

forwardCompatibleEnumsByDefault

Required

false

Description

Make enums forward compatible by default. When enabled, provides an API to access the raw value when the enum value fails to map to any of the known enum members. Forces

Default Value

on for new SDKs

generateOptionalUnionAccessors

Required

false

Description

Generate optional accessor methods for non-discriminated union types instead of the generic

method. When enabled, generates

accessors for each union member.

Default Value

on for new SDKs

generateUnionDocs

Required

false

Description

Generate Supported Types documentation for union model pages. Non-discriminated unions show factory method examples; discriminated unions show a discriminator-value-to-type mapping table.

Default Value

on for new SDKs

inferUnionDiscriminators

Required

false

Description

Infer union discriminators for

s missing explicit OpenAPI discriminator mapping. This is a common option shared across languages.

Default Value

on for new SDKs

Name	Required	Default Value	Description
unionStrategy	false	populated-fields	Strategy for deserializing union types. tries each type in order and returns the first valid match. uses sophisticated candidate scoring based on mapped fields, enum fields, and JSON size to select the best matching union member.
forwardCompatibleUnionsByDefault	false	on for new SDKs	Enable forward compatibility for unions in responses. When true, unions are open to unknown values with raw JSON fallback. Individual unions can be controlled with .
forwardCompatibleEnumsByDefault	false	on for new SDKs	Make enums forward compatible by default. When enabled, provides an API to access the raw value when the enum value fails to map to any of the known enum members. Forces .
generateOptionalUnionAccessors	false	on for new SDKs	Generate optional accessor methods for non-discriminated union types instead of the generic method. When enabled, generates accessors for each union member.
generateUnionDocs	false	on for new SDKs	Generate Supported Types documentation for union model pages. Non-discriminated unions show factory method examples; discriminated unions show a discriminator-value-to-type mapping table.
inferUnionDiscriminators	false	on for new SDKs	Infer union discriminators for s missing explicit OpenAPI discriminator mapping. This is a common option shared across languages.

Models and docs


java:
  inputModelSuffix: "input"
  outputModelSuffix: "output"
  showSetterGetterTypesInDocs: true
  explicitDocImports: true

Name

inputModelSuffix

Required

false

Description

The suffix to add to models with writeOnly fields that are created as input models. This is a common option shared across languages.

Default Value

input

outputModelSuffix

Required

false

Description

The suffix to add to models with readOnly fields that are created as output models. This is a common option shared across languages.

Default Value

output

showSetterGetterTypesInDocs

Required

false

Description

Show separate Setter Type and Getter Type columns in model documentation instead of a single Type column. Only takes effect when

is also enabled.

Default Value

on for new SDKs

explicitDocImports

Required

false

Description

Use explicit imports instead of wildcard imports in doc usage examples to avoid ambiguous class references.

Default Value

on for new SDKs

Name	Required	Default Value	Description
inputModelSuffix	false	input	The suffix to add to models with writeOnly fields that are created as input models. This is a common option shared across languages.
outputModelSuffix	false	output	The suffix to add to models with readOnly fields that are created as output models. This is a common option shared across languages.
showSetterGetterTypesInDocs	false	on for new SDKs	Show separate Setter Type and Getter Type columns in model documentation instead of a single Type column. Only takes effect when is also enabled.
explicitDocImports	false	on for new SDKs	Use explicit imports instead of wildcard imports in doc usage examples to avoid ambiguous class references.

Customization and logging


java:
  enableCustomCodeRegions: false
  enableSlf4jLogging: true

Name

enableCustomCodeRegions

Required

false

Description

Allow custom code to be inserted into the generated SDK.

Default Value

false

enableSlf4jLogging

Required

false

Description

Enable SLF4j logging integration. Users can configure their preferred SLF4j implementation (Logback, Log4j2, etc.).

Default Value

on for new SDKs

Name	Required	Default Value	Description
enableCustomCodeRegions	false	false	Allow custom code to be inserted into the generated SDK.
enableSlf4jLogging	false	on for new SDKs	Enable SLF4j logging integration. Users can configure their preferred SLF4j implementation (Logback, Log4j2, etc.).

Last updated on May 6, 2026