# 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

```yml
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"
```

<Table
  data={[
    {
      name: "version",
      required: "true",
      default: "0.0.1",
      description: "The current version of the SDK.",
    },
    {
      name: "templateVersion",
      required: "false",
      default: "v2",
      description: "The template version to use. Must be `v2`.",
    },
    {
      name: "projectName",
      required: "true",
      default: "openapi",
      description:
        "Assigns Gradle `rootProject.name`, which gives a name to the Gradle build. See [Gradle Naming](https://docs.gradle.org/current/userguide/multi_project_builds.html#naming_recommendations).",
    },
    {
      name: "groupID",
      required: "true",
      default: "org.openapis",
      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. `<groupId>.my-artifact`).",
    },
    {
      name: "artifactID",
      required: "true",
      default: "openapi",
      description:
        "The artifactID is used as the final simple name in the base package if `packageName` 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. `com.yourorg.<artifactId>`).",
    },
    {
      name: "packageName",
      required: "false",
      default: "`<groupId>.<artifactId>`",
      description:
        "The base package name for generated classes. If not present, `<groupId>.<artifactId>` will be used.",
    },
    {
      name: "ossrhURL",
      required: "false",
      default: "N/A",
      description:
        "The URL of the staging repository to publish the SDK artifact to.",
    },
    {
      name: "githubURL",
      required: "for publishing",
      default: "github.com/owner/repo",
      description:
        "The GitHub URL where the artifact is hosted. Sets metadata required by Maven.",
    },
    {
      name: "companyName",
      required: "for publishing",
      default: "My Company",
      description: "The name of the company. Sets metadata required by Maven.",
    },
    {
      name: "companyURL",
      required: "for publishing",
      default: "www.mycompany.com",
      description:
        "The company homepage URL. Sets metadata required by Maven.",
    },
    {
      name: "companyEmail",
      required: "for publishing",
      default: "info@mycompany.com",
      description:
        "A support email address for the company. Sets metadata required by Maven.",
    },
    {
      name: "description",
      required: "false",
      default: "SDK enabling Java developers to easily integrate with the {CompanyName} API.",
      description:
        "The description to use in the Maven POM file.",
    },
    {
      name: "license",
      required: "false",
      default: "MIT License",
      description:
        "License information. Defaults to the MIT license if not otherwise specified.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Build and language

```yml
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
```

## API surface shape

```yml
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
```

### Import paths

## Errors

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

## Async and streaming

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

## Unions and enums

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

<Table
  data={[
    {
      name: "unionStrategy",
      required: "false",
      default: "populated-fields",
      description:
        "Strategy for deserializing union types. `left-to-right` tries each type in order and returns the first valid match. `populated-fields` uses sophisticated candidate scoring based on mapped fields, enum fields, and JSON size to select the best matching union member.",
    },
    {
      name: "forwardCompatibleUnionsByDefault",
      required: "false",
      default: "on for new SDKs",
      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 `x-speakeasy-unknown-values: allow/disallow`.",
    },
    {
      name: "forwardCompatibleEnumsByDefault",
      required: "false",
      default: "on for new SDKs",
      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 `unionStrategy: populated-fields`.",
    },
    {
      name: "generateOptionalUnionAccessors",
      required: "false",
      default: "on for new SDKs",
      description:
        "Generate optional accessor methods for non-discriminated union types instead of the generic `value()` method. When enabled, generates `Optional<SubType> subType()` accessors for each union member.",
    },
    {
      name: "generateUnionDocs",
      required: "false",
      default: "on for new SDKs",
      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.",
    },
    {
      name: "inferUnionDiscriminators",
      required: "false",
      default: "on for new SDKs",
      description:
        "Infer union discriminators for `oneOf`s missing explicit OpenAPI discriminator mapping. This is a common option shared across languages.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Models and docs

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

## Customization and logging

```yml
java:
  enableCustomCodeRegions: false
  enableSlf4jLogging: true
```