feat: add optional getters for nullable fields

[jorgerod]

Closes: #24002

PR checklist

• Read the contribution guidelines.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.
  @bbdouglas (2017/07) @sreeshas (2017/08) @jfiala (2017/08) @lukoyanov (2017/09) @cbornet (2017/09) @jeff9finger (2018/01) @karismann (2019/03) @Zomzog (2019/04) @lwlee2608 (2019/10) @martin-mfg (2023/08) @wing328

---

Summary by cubic

Adds an opt-in optionalGettersForNullableFieldsOnly option that makes getters return Optional<T> for non-required, non-nullable fields in Java and JavaSpring generators (closes #24002). Off by default; fields and setters keep their raw types, and JsonNullable, nullable, and required fields are unaffected.

New Features

• Adds the option to AbstractJavaCodegen and enables it in Java restclient, resttemplate, and webclient and JavaSpring POJO templates.
• Keeps raw getters and annotations for discriminators and inherited properties.
• Adds Spring Boot 4 + Jackson 3 + JSpecify sample configs, updated docs, and Java/Spring tests.
• Removes the generateInsecureTlsHook option and the trust-all TLS hook from generated ApiClient.
• Pins the build toolchain to OpenJDK 21 in .tool-versions and bumps generated samples to 7.26.0-SNAPSHOT.

Bug Fixes

• Fixes indentation in generated nullable getters.
• Propagates the discriminator property to subtype models so discriminators are not wrapped in Optional when the option is enabled.

^{Written for commit 4784547. Summary will update on new commits.}

[cubic-dev-ai]

7 issues found across 212 files

<sub>Note: This PR contains a large number of files. cubic only reviews up to 100 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.
On a pro plan you can use ultrareview for larger PRs.

Re-trigger cubic</sub>

[jorgerod]

Hi @wing328

This PR has been waiting to be reviewed for over a month. I know there are a lot of PRs to review and that it's complicated, but it's pretty important to me.

Thank you very much

[cubic-dev-ai]

All reported issues were addressed across 51 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

3 issues found across 24 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/generators/go-gin-server.md">

<violation number="1" location="docs/generators/go-gin-server.md:24">
P3: These docs/generators/*.md files are regenerated from the codegen descriptions by export_docs_generators.sh, so editing the markdown directly diverges from the source and will be overwritten. Update the interfaceOnly description in GoGinServerCodegen.java (line 121) to "without the implementation files" and regenerate the docs instead.</violation>
</file>

<file name="docs/generators/cpp-boost-beast-client.md">

<violation number="1" location="docs/generators/cpp-boost-beast-client.md:242">
P2: The FEATURE SET table was rewritten to values that contradict CppBoostBeastClientCodegen at HEAD. The generator still includes MultiServer, ParameterStyling, Callbacks, LinkObjects, Cookie, Polymorphism, Union, oneOf, anyOf, allOf, and not (these should be ✓, not ✗), and still excludes Decimal, Byte, Binary, Date, DateTime, and Password (these should be ✗, not ✓). Sixteen rows are now wrong, which actively misleads users about the generator's supported features. Revert these changes or update the codegen first, then regenerate the doc.</violation>
</file>

<file name="docs/generators/kotlin.md">

<violation number="1" location="docs/generators/kotlin.md:53">
P2: The Kotlin client documentation falsely describes `useJackson3` as unsupported. Document its supported `jvm-okhttp4` and `jvm-spring-restclient` libraries and their prerequisites.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: These docs/generators/*.md files are regenerated from the codegen descriptions by export_docs_generators.sh, so editing the markdown directly diverges from the source and will be overwritten. Update the interfaceOnly description in GoGinServerCodegen.java (line 121) to "without the implementation files" and regenerate the docs instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/generators/go-gin-server.md, line 24:

<comment>These docs/generators/*.md files are regenerated from the codegen descriptions by export_docs_generators.sh, so editing the markdown directly diverges from the source and will be overwritten. Update the interfaceOnly description in GoGinServerCodegen.java (line 121) to "without the implementation files" and regenerate the docs instead.</comment>

<file context>
@@ -21,7 +21,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |enumClassPrefix|Prefix enum with class name| |false|
 |hideGenerationTimestamp|Hides the generation timestamp when files are generated.| |true|
-|interfaceOnly|Whether to generate only API interface stubs instead of the API implementation files.| |false|
+|interfaceOnly|Whether to generate only API interface stubs without the implementation files.| |false|
 |packageName|Go package name (convention: lowercase).| |openapi|
 |packageVersion|Go package version.| |1.0.0|
</file context>

[cubic-dev-ai]

12 issues found across 176 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/client/petstore/java/webclient-springBoot4-jackson3-jspecify-optional-getters/src/main/java/org/openapitools/client/ServerVariable.java">

<violation number="1" location="samples/client/petstore/java/webclient-springBoot4-jackson3-jspecify-optional-getters/src/main/java/org/openapitools/client/ServerVariable.java:21">
P3: The version bump regenerated most of this sample directory, but DefaultApi.java still carries "Generator version: 7.25.0-SNAPSHOT". A sample generated in one pass should be consistent; regenerate the sample so every file reports 7.26.0-SNAPSHOT.</violation>
</file>

<file name="samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/model/Foo.java">

<violation number="1" location="samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/model/Foo.java:135">
P2: The nullable getters are declared non-null even though their fields and setters permit `null`, so JSpecify callers receive an incorrect nullness contract. Add `@Nullable` to every raw nullable getter return type, including `getNullableDt`, `getNullableBinary`, `getNullableListMinIntems`, `getNullableNumber`, and `getNullableColor`.</violation>
</file>

<file name="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters/docs/RequiredAndNullable.md">

<violation number="1" location="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters/docs/RequiredAndNullable.md:10">
P3: The generated doc omits the `[optional]` note for the non-required fields `str`, `_file`, `color`, and `_list`. The model marks these `required = false` (only `onlyRequired` is required), and sibling docs (Foo.md, FileContent.md) show `[optional]` for non-required fields, so the doc is inconsistent with the model and with doc conventions. Regenerate the sample so the pojo_doc template annotates these as optional.</violation>
</file>

<file name="docs/generators/java.md">

<violation number="1">
P2: This PR adds the new user-facing option `optionalGettersForNullableFieldsOnly` (registered as a CliOption in AbstractJavaCodegen at line 377 and exposed via the new sample configs), but this delta deletes its row from docs/generators/java.md, leaving the new option completely undocumented in every docs file. The removed description matches the current CliOption text exactly, and this is a newly introduced option (it is absent from the target-branch java.md), so nothing justifies dropping the entry. Since docs/generators/*.md are regenerated from `config-help` (bin/utils/export_generator.sh), keeping the docs row in sync with the code also keeps the generated docs consistent. Restore the option row so users can discover the feature.</violation>
</file>

<file name="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters/docs/FooApi.md">

<violation number="1" location="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters/docs/FooApi.md:33">
P3: The example block in this generated doc does not compile if copied. `java.time.Instant` has no public constructor (only factory methods like `Instant.now()` / `ofEpochSecond`), so `new java.time.Instant()` is a compile error. In addition, the example imports `org.openapitools.client.models.*`, but the generated model package is `org.openapitools.client.model` (see `FooApi.java` line 5 `import org.openapitools.client.model.Foo;`), so `Foo` does not resolve. The root cause is the shared Java `api_doc.mustache` template (identical broken example already exists in the pre-existing `restclient-springBoot4-jackson3-jspecify` sample), so the fix belongs there rather than in this generated file.</violation>
</file>

<file name="samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/src/main/java/org/openapitools/client/api/FooApi.java">

<violation number="1" location="samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/src/main/java/org/openapitools/client/api/FooApi.java:85">
P3: The cookie-param statement body is not indented: `if (dtCookie != null)` and `localVarCookieParams.add("dtCookie", ...)` are emitted at the same column, so the `if` body reads as a sibling line. The indentation comes from the resttemplate `api.mustache` (the `{{#cookieParams}}if (...)\nlocalVarCookieParams.add(...)` block), and the same pattern is generated for every resttemplate cookie param. Fix the indentation in the template (indent the `add` line one level deeper) and regenerate the samples; hand-editing the generated file would be overwritten.</violation>
</file>

<file name="samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES">

<violation number="1" location="samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES:32">
P2: The sample was regenerated and the API split into FileApi/FooApi/RequiredAndNullableApi/UploadApi, but the stale files docs/DefaultApi.md, src/main/java/org/openapitools/client/api/DefaultApi.java, src/test/java/org/openapitools/client/api/DefaultApiTest.java, and src/test/java/org/openapitools/client/model/FooTest.java remain on disk and git-tracked even though they were removed from (or never added to) .openapi-generator/FILES. DefaultApi.java is still generated at 7.25.0-SNAPSHOT while the regenerated files are 7.26.0-SNAPSHOT, so it is a leftover from the previous generation. Delete these four stale files so the sample directory matches its manifest and a fresh regeneration produces no dirty output.</violation>
</file>

<file name="samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/README.md">

<violation number="1" location="samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/README.md:118">
P3: The regenerated sample still contains stale DefaultApi.java and docs/DefaultApi.md that are not part of the current generator output — they are absent from .openapi-generator/FILES and duplicate the endpoints now provided by FileApi/FooApi/UploadApi. Delete these leftover files so the sample matches the README and the FILES manifest.</violation>
</file>

<file name="samples/client/petstore/java/webclient-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES">

<violation number="1" location="samples/client/petstore/java/webclient-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES:33">
P2: The FILES manifest drops `docs/DefaultApi.md` and `src/main/java/org/openapitools/client/api/DefaultApi.java`, but both files are still present and git-tracked in the sample directory at this PR head (verified via git ls-files and find). The sample's api/openapi.yaml only defines `/foo/{dtParam}`, `/requiredAndNullable`, `/upload`, `/uploadFiles`, `/file/{id}` — there is no default API anymore, so these DefaultApi files are stale leftovers. Because they were removed from FILES, a future regeneration will no longer clean them up (the generator only deletes files listed in the previous FILES), leaving the sample permanently out of sync with its manifest. Delete the stale DefaultApi.java/DefaultApi.md (and the orphaned src/test/.../DefaultApiTest.java and FooTest.java) so the sample matches the FILES manifest.</violation>
</file>

<file name="samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/api/UploadFilesApi.java">

<violation number="1" location="samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/api/UploadFilesApi.java:65">
P3: The `file` request part is optional (`required = false`) but is not annotated `@Nullable`. The package is `@NullMarked` (package-info.java), so under JSpecify unannotated parameters default to non-null, while Spring may pass null for an absent part. Annotate the parameter `@Nullable` (consistent with how optional params are annotated in FooApi.java) or drop the now-unused `@Nullable` import.</violation>
</file>

<file name="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES">

<violation number="1">
P2: The FILES manifest now omits docs/DefaultApi.md and src/main/java/org/openapitools/client/api/DefaultApi.java, but those files (plus DefaultApiTest.java and FooTest.java) are still present and git-tracked in the sample directory. The committed sample is out of sync with its own manifest: the DefaultApi sources reference the API that was replaced by FileApi/FooApi/RequiredAndNullableApi/UploadApi, and regenerating the sample will either prune these stale files (showing them as deletions in the samples check) or leave dead files that a clean generation would not produce. Delete the four stale files so the committed sample matches the generated output.</violation>
</file>

<file name="samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/model/FileContent.java">

<violation number="1" location="samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/model/FileContent.java:7">
P2: The generated code uses Jackson 2 annotation classes (com.fasterxml.jackson.annotation.*) while the pom pulls in Jackson 3 (tools.jackson.core/jackson-dataformat-xml). Jackson 3 reads annotations from tools.jackson.annotation only, so @JsonValue/@JsonCreator on VirusScanEnum and @JsonProperty on the accessors are ignored: VirusScanEnum then serializes as "CLEAN"/"DETECTED" instead of the spec values "clean"/"detected", breaking the API contract. For a Jackson 3/Spring Boot 4 sample the annotation imports should be tools.jackson.annotation.*.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The nullable getters are declared non-null even though their fields and setters permit null, so JSpecify callers receive an incorrect nullness contract. Add @Nullable to every raw nullable getter return type, including getNullableDt, getNullableBinary, getNullableListMinIntems, getNullableNumber, and getNullableColor.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/model/Foo.java, line 135:

<comment>The nullable getters are declared non-null even though their fields and setters permit `null`, so JSpecify callers receive an incorrect nullness contract. Add `@Nullable` to every raw nullable getter return type, including `getNullableDt`, `getNullableBinary`, `getNullableListMinIntems`, `getNullableNumber`, and `getNullableColor`.</comment>

<file context>
@@ -93,18 +108,41 @@ public Foo dt(OffsetDateTime dt) {
+  @JsonProperty("nullableDt")
+  @JacksonXmlProperty(localName = "nullableDt")
+  @XmlElement(name = "nullableDt")
+  public OffsetDateTime getNullableDt() {
+    return nullableDt;
+  }
</file context>

[cubic-dev-ai]

P2: The sample was regenerated and the API split into FileApi/FooApi/RequiredAndNullableApi/UploadApi, but the stale files docs/DefaultApi.md, src/main/java/org/openapitools/client/api/DefaultApi.java, src/test/java/org/openapitools/client/api/DefaultApiTest.java, and src/test/java/org/openapitools/client/model/FooTest.java remain on disk and git-tracked even though they were removed from (or never added to) .openapi-generator/FILES. DefaultApi.java is still generated at 7.25.0-SNAPSHOT while the regenerated files are 7.26.0-SNAPSHOT, so it is a leftover from the previous generation. Delete these four stale files so the sample directory matches its manifest and a fresh regeneration produces no dirty output.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES, line 32:

<comment>The sample was regenerated and the API split into FileApi/FooApi/RequiredAndNullableApi/UploadApi, but the stale files docs/DefaultApi.md, src/main/java/org/openapitools/client/api/DefaultApi.java, src/test/java/org/openapitools/client/api/DefaultApiTest.java, and src/test/java/org/openapitools/client/model/FooTest.java remain on disk and git-tracked even though they were removed from (or never added to) .openapi-generator/FILES. DefaultApi.java is still generated at 7.25.0-SNAPSHOT while the regenerated files are 7.26.0-SNAPSHOT, so it is a leftover from the previous generation. Delete these four stale files so the sample directory matches its manifest and a fresh regeneration produces no dirty output.</comment>

<file context>
@@ -24,12 +29,23 @@ src/main/java/org/openapitools/client/RFC3339InstantDeserializer.java
 src/main/java/org/openapitools/client/ServerConfiguration.java
 src/main/java/org/openapitools/client/ServerVariable.java
-src/main/java/org/openapitools/client/api/DefaultApi.java
+src/main/java/org/openapitools/client/api/FileApi.java
+src/main/java/org/openapitools/client/api/FooApi.java
+src/main/java/org/openapitools/client/api/RequiredAndNullableApi.java
</file context>

[cubic-dev-ai]

P2: The FILES manifest drops docs/DefaultApi.md and src/main/java/org/openapitools/client/api/DefaultApi.java, but both files are still present and git-tracked in the sample directory at this PR head (verified via git ls-files and find). The sample's api/openapi.yaml only defines /foo/{dtParam}, /requiredAndNullable, /upload, /uploadFiles, /file/{id} — there is no default API anymore, so these DefaultApi files are stale leftovers. Because they were removed from FILES, a future regeneration will no longer clean them up (the generator only deletes files listed in the previous FILES), leaving the sample permanently out of sync with its manifest. Delete the stale DefaultApi.java/DefaultApi.md (and the orphaned src/test/.../DefaultApiTest.java and FooTest.java) so the sample matches the FILES manifest.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/webclient-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES, line 33:

<comment>The FILES manifest drops `docs/DefaultApi.md` and `src/main/java/org/openapitools/client/api/DefaultApi.java`, but both files are still present and git-tracked in the sample directory at this PR head (verified via git ls-files and find). The sample's api/openapi.yaml only defines `/foo/{dtParam}`, `/requiredAndNullable`, `/upload`, `/uploadFiles`, `/file/{id}` — there is no default API anymore, so these DefaultApi files are stale leftovers. Because they were removed from FILES, a future regeneration will no longer clean them up (the generator only deletes files listed in the previous FILES), leaving the sample permanently out of sync with its manifest. Delete the stale DefaultApi.java/DefaultApi.md (and the orphaned src/test/.../DefaultApiTest.java and FooTest.java) so the sample matches the FILES manifest.</comment>

<file context>
@@ -17,19 +22,31 @@ pom.xml
 src/main/java/org/openapitools/client/ServerVariable.java
 src/main/java/org/openapitools/client/StringUtil.java
-src/main/java/org/openapitools/client/api/DefaultApi.java
+src/main/java/org/openapitools/client/api/FileApi.java
+src/main/java/org/openapitools/client/api/FooApi.java
+src/main/java/org/openapitools/client/api/RequiredAndNullableApi.java
</file context>

[cubic-dev-ai]

P2: The FILES manifest now omits docs/DefaultApi.md and src/main/java/org/openapitools/client/api/DefaultApi.java, but those files (plus DefaultApiTest.java and FooTest.java) are still present and git-tracked in the sample directory. The committed sample is out of sync with its own manifest: the DefaultApi sources reference the API that was replaced by FileApi/FooApi/RequiredAndNullableApi/UploadApi, and regenerating the sample will either prune these stale files (showing them as deletions in the samples check) or leave dead files that a clean generation would not produce. Delete the four stale files so the committed sample matches the generated output.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES, line 25:

<comment>The FILES manifest now omits docs/DefaultApi.md and src/main/java/org/openapitools/client/api/DefaultApi.java, but those files (plus DefaultApiTest.java and FooTest.java) are still present and git-tracked in the sample directory. The committed sample is out of sync with its own manifest: the DefaultApi sources reference the API that was replaced by FileApi/FooApi/RequiredAndNullableApi/UploadApi, and regenerating the sample will either prune these stale files (showing them as deletions in the samples check) or leave dead files that a clean generation would not produce. Delete the four stale files so the committed sample matches the generated output.</comment>

<file context>
@@ -17,17 +22,29 @@ pom.xml
 settings.gradle
 src/main/AndroidManifest.xml
 src/main/java/org/openapitools/client/ApiClient.java
+src/main/java/org/openapitools/client/ExceptionProvider.java
 src/main/java/org/openapitools/client/JavaTimeFormatter.java
 src/main/java/org/openapitools/client/RFC3339DateFormat.java
</file context>

[cubic-dev-ai]

P2: The generated code uses Jackson 2 annotation classes (com.fasterxml.jackson.annotation.) while the pom pulls in Jackson 3 (tools.jackson.core/jackson-dataformat-xml). Jackson 3 reads annotations from tools.jackson.annotation only, so @JsonValue/@JsonCreator on VirusScanEnum and @JsonProperty on the accessors are ignored: VirusScanEnum then serializes as "CLEAN"/"DETECTED" instead of the spec values "clean"/"detected", breaking the API contract. For a Jackson 3/Spring Boot 4 sample the annotation imports should be tools.jackson.annotation..

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/model/FileContent.java, line 7:

<comment>The generated code uses Jackson 2 annotation classes (com.fasterxml.jackson.annotation.*) while the pom pulls in Jackson 3 (tools.jackson.core/jackson-dataformat-xml). Jackson 3 reads annotations from tools.jackson.annotation only, so @JsonValue/@JsonCreator on VirusScanEnum and @JsonProperty on the accessors are ignored: VirusScanEnum then serializes as "CLEAN"/"DETECTED" instead of the spec values "clean"/"detected", breaking the API contract. For a Jackson 3/Spring Boot 4 sample the annotation imports should be tools.jackson.annotation.*.</comment>

<file context>
@@ -0,0 +1,273 @@
+import java.util.Objects;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+import org.jspecify.annotations.Nullable;
+import java.time.OffsetDateTime;
</file context>

[cubic-dev-ai]

P3: The generated doc omits the [optional] note for the non-required fields str, _file, color, and _list. The model marks these required = false (only onlyRequired is required), and sibling docs (Foo.md, FileContent.md) show [optional] for non-required fields, so the doc is inconsistent with the model and with doc conventions. Regenerate the sample so the pojo_doc template annotates these as optional.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters/docs/RequiredAndNullable.md, line 10:

<comment>The generated doc omits the `[optional]` note for the non-required fields `str`, `_file`, `color`, and `_list`. The model marks these `required = false` (only `onlyRequired` is required), and sibling docs (Foo.md, FileContent.md) show `[optional]` for non-required fields, so the doc is inconsistent with the model and with doc conventions. Regenerate the sample so the pojo_doc template annotates these as optional.</comment>

<file context>
@@ -0,0 +1,17 @@
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+|**str** | **String** |  |  |
+|**_file** | **File** |  |  |
+|**color** | **String** |  |  |
</file context>

[cubic-dev-ai]

P3: The example block in this generated doc does not compile if copied. java.time.Instant has no public constructor (only factory methods like Instant.now() / ofEpochSecond), so new java.time.Instant() is a compile error. In addition, the example imports org.openapitools.client.models.*, but the generated model package is org.openapitools.client.model (see FooApi.java line 5 import org.openapitools.client.model.Foo;), so Foo does not resolve. The root cause is the shared Java api_doc.mustache template (identical broken example already exists in the pre-existing restclient-springBoot4-jackson3-jspecify sample), so the fix belongs there rather than in this generated file.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify-optional-getters/docs/FooApi.md, line 33:

<comment>The example block in this generated doc does not compile if copied. `java.time.Instant` has no public constructor (only factory methods like `Instant.now()` / `ofEpochSecond`), so `new java.time.Instant()` is a compile error. In addition, the example imports `org.openapitools.client.models.*`, but the generated model package is `org.openapitools.client.model` (see `FooApi.java` line 5 `import org.openapitools.client.model.Foo;`), so `Foo` does not resolve. The root cause is the shared Java `api_doc.mustache` template (identical broken example already exists in the pre-existing `restclient-springBoot4-jackson3-jspecify` sample), so the fix belongs there rather than in this generated file.</comment>

<file context>
@@ -0,0 +1,79 @@
+        defaultClient.setBasePath("http://localhost");
+
+        FooApi apiInstance = new FooApi(defaultClient);
+        java.time.Instant dtParam = new java.time.Instant(); // java.time.Instant | 
+        java.time.Instant dtQuery = new java.time.Instant(); // java.time.Instant | 
+        java.time.Instant dtCookie = new java.time.Instant(); // java.time.Instant | 
</file context>

[cubic-dev-ai]

P3: The cookie-param statement body is not indented: if (dtCookie != null) and localVarCookieParams.add("dtCookie", ...) are emitted at the same column, so the if body reads as a sibling line. The indentation comes from the resttemplate api.mustache (the {{#cookieParams}}if (...)\nlocalVarCookieParams.add(...) block), and the same pattern is generated for every resttemplate cookie param. Fix the indentation in the template (indent the add line one level deeper) and regenerate the samples; hand-editing the generated file would be overwritten.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/src/main/java/org/openapitools/client/api/FooApi.java, line 85:

<comment>The cookie-param statement body is not indented: `if (dtCookie != null)` and `localVarCookieParams.add("dtCookie", ...)` are emitted at the same column, so the `if` body reads as a sibling line. The indentation comes from the resttemplate `api.mustache` (the `{{#cookieParams}}if (...)\nlocalVarCookieParams.add(...)` block), and the same pattern is generated for every resttemplate cookie param. Fix the indentation in the template (indent the `add` line one level deeper) and regenerate the samples; hand-editing the generated file would be overwritten.</comment>

<file context>
@@ -0,0 +1,122 @@
+        
+
+        if (dtCookie != null)
+        localVarCookieParams.add("dtCookie", apiClient.parameterToString(dtCookie));
+
+        final String[] localVarAccepts = { 
</file context>

[cubic-dev-ai]

P3: The regenerated sample still contains stale DefaultApi.java and docs/DefaultApi.md that are not part of the current generator output — they are absent from .openapi-generator/FILES and duplicate the endpoints now provided by FileApi/FooApi/UploadApi. Delete these leftover files so the sample matches the README and the FILES manifest.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/resttemplate-springBoot4-jackson3-jspecify-optional-getters/README.md, line 118:

<comment>The regenerated sample still contains stale DefaultApi.java and docs/DefaultApi.md that are not part of the current generator output — they are absent from .openapi-generator/FILES and duplicate the endpoints now provided by FileApi/FooApi/UploadApi. Delete these leftover files so the sample matches the README and the FILES manifest.</comment>

<file context>
@@ -114,14 +115,18 @@ All URIs are relative to *http://localhost*
-*DefaultApi* | [**fileIdGet**](docs/DefaultApi.md#fileIdGet) | **GET** /file/{id} | 
-*DefaultApi* | [**fooDtParamGet**](docs/DefaultApi.md#fooDtParamGet) | **GET** /foo/{dtParam} | 
-*DefaultApi* | [**uploadPost**](docs/DefaultApi.md#uploadPost) | **POST** /upload | 
+*FileApi* | [**fileIdGet**](docs/FileApi.md#fileIdGet) | **GET** /file/{id} | 
+*FooApi* | [**fooDtParamGet**](docs/FooApi.md#fooDtParamGet) | **GET** /foo/{dtParam} | 
+*RequiredAndNullableApi* | [**requiredAndNullablePost**](docs/RequiredAndNullableApi.md#requiredAndNullablePost) | **POST** /requiredAndNullable | 
</file context>

[cubic-dev-ai]

P3: The file request part is optional (required = false) but is not annotated @Nullable. The package is @NullMarked (package-info.java), so under JSpecify unannotated parameters default to non-null, while Spring may pass null for an absent part. Annotate the parameter @Nullable (consistent with how optional params are annotated in FooApi.java) or drop the now-unused @Nullable import.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/openapi3/server/petstore/springboot-4-jspecify-optional-getters/src/main/java/org/openapitools/api/UploadFilesApi.java, line 65:

<comment>The `file` request part is optional (`required = false`) but is not annotated `@Nullable`. The package is `@NullMarked` (package-info.java), so under JSpecify unannotated parameters default to non-null, while Spring may pass null for an absent part. Annotate the parameter `@Nullable` (consistent with how optional params are annotated in FooApi.java) or drop the now-unused `@Nullable` import.</comment>

<file context>
@@ -0,0 +1,71 @@
+        consumes = { "multipart/form-data" }
+    )
+    default ResponseEntity<Void> uploadFilesPost(
+        @Parameter(name = "file", description = "") @RequestPart(value = "file", required = false) List<MultipartFile> file
+    ) {
+        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
</file context>

[cubic-dev-ai]

5 issues found across 17 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/openapi3/client/extensions/x-auth-id-alias/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java">

<violation number="1" location="samples/openapi3/client/extensions/x-auth-id-alias/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java:1263">
P1: This sample removed disableCertificateValidation() and its SSL imports, but its generator config does not set generateInsecureTlsHook, which defaults to true in JavaClientCodegen (additionalProperties.put(GENERATE_INSECURE_TLS_HOOK, true)). Regenerating this sample from the template will re-add the method and imports, so the committed sample will not match CI's regenerated output and the sample-verification job will fail. Add `generateInsecureTlsHook: false` to bin/configs/java-jersey2-extensions-x-auth-id-alias.yaml so the committed sample matches the generator output.</violation>
</file>

<file name="samples/openapi3/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java">

<violation number="1" location="samples/openapi3/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java:1434">
P2: This removes `disableCertificateValidation` from a generated file, but the generator still emits it: `Java/libraries/jersey2/ApiClient.mustache` wraps the method in `{{#generateInsecureTlsHook}}`, and `JavaClientCodegen.java` defaults `generateInsecureTlsHook` to `true`. The config that generates this sample (`bin/configs/java-jersey2-8.yaml`) does not set `generateInsecureTlsHook: false`, so regenerating the sample (which CI does and compares against HEAD) restores the method and flags this file as out of sync, reverting the removal. The removal belongs in the template and/or config flag, not a hand edit of the generated sample.</violation>
</file>

<file name="docs/generators/java-microprofile.md">

<violation number="1" location="docs/generators/java-microprofile.md:59">
P2: This doc row is auto-generated by `config-help -g java-microprofile --format markdown`, derived from the generator's `cliOptions`. `generateInsecureTlsHook` is still registered in `JavaClientCodegen` (line 287) and `JavaMicroprofileServerCodegen extends JavaClientCodegen` without removing it, so `config-help` for java-microprofile still lists the option. Removing the row by hand makes the checked-in doc drift from the actual config surface, and the next `bin/utils/export_docs_generators.sh` run (which CI expects to be clean) will re-add it. If the intent is to drop the option for microprofile, the generator must stop exposing it in `JavaMicroprofileServerCodegen`, not just edit the doc.</violation>
</file>

<file name="samples/client/petstore/java/jersey2-java8-localdatetime/src/main/java/org/openapitools/client/ApiClient.java">

<violation number="1" location="samples/client/petstore/java/jersey2-java8-localdatetime/src/main/java/org/openapitools/client/ApiClient.java:1371">
P2: Removing disableCertificateValidation from this generated ApiClient.java makes the committed sample inconsistent with the generator output. The jersey2 template still emits the method under {{#generateInsecureTlsHook}}, whose default is true (JavaClientCodegen.java:287,532-536), and bin/configs/java-jersey2-java8-localdatetime.yaml does not set generateInsecureTlsHook: false. Regenerating this sample (as the samples-verification CI step does) will restore the method and leave a non-clean git diff, failing CI. Either set generateInsecureTlsHook: false in that config, or keep the method in the sample.</violation>
</file>

<file name="samples/client/petstore/java/webclient-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES">

<violation number="1">
P2: These 6 test files were removed from the .openapi-generator/FILES manifest but still exist in the sample and are not protected by .openapi-generator-ignore (it is empty). The manifest now disagrees with the sample contents, and the files carry the generator's auto-generated header, so a fresh regeneration will re-emit them and re-list them in FILES, producing a diff that fails the sample-verification CI check. If the tests are meant to be preserved as manually-maintained generated files, add them to .openapi-generator-ignore; otherwise delete them from the sample so FILES and disk stay in sync.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: This sample removed disableCertificateValidation() and its SSL imports, but its generator config does not set generateInsecureTlsHook, which defaults to true in JavaClientCodegen (additionalProperties.put(GENERATE_INSECURE_TLS_HOOK, true)). Regenerating this sample from the template will re-add the method and imports, so the committed sample will not match CI's regenerated output and the sample-verification job will fail. Add generateInsecureTlsHook: false to bin/configs/java-jersey2-extensions-x-auth-id-alias.yaml so the committed sample matches the generator output.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/openapi3/client/extensions/x-auth-id-alias/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java, line 1263:

<comment>This sample removed disableCertificateValidation() and its SSL imports, but its generator config does not set generateInsecureTlsHook, which defaults to true in JavaClientCodegen (additionalProperties.put(GENERATE_INSECURE_TLS_HOOK, true)). Regenerating this sample from the template will re-add the method and imports, so the committed sample will not match CI's regenerated output and the sample-verification job will fail. Add `generateInsecureTlsHook: false` to bin/configs/java-jersey2-extensions-x-auth-id-alias.yaml so the committed sample matches the generator output.</comment>

<file context>
@@ -37,13 +37,6 @@
 import java.io.InputStream;
 
 import java.net.URI;
-import javax.net.ssl.SSLContext;
-import javax.net.ssl.TrustManager;
-import javax.net.ssl.X509TrustManager;
-import java.security.cert.X509Certificate;
-import java.security.KeyManagementException;
-import java.security.NoSuchAlgorithmException;
</file context>

[cubic-dev-ai]

P2: This removes disableCertificateValidation from a generated file, but the generator still emits it: Java/libraries/jersey2/ApiClient.mustache wraps the method in {{#generateInsecureTlsHook}}, and JavaClientCodegen.java defaults generateInsecureTlsHook to true. The config that generates this sample (bin/configs/java-jersey2-8.yaml) does not set generateInsecureTlsHook: false, so regenerating the sample (which CI does and compares against HEAD) restores the method and flags this file as out of sync, reverting the removal. The removal belongs in the template and/or config flag, not a hand edit of the generated sample.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/openapi3/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java, line 1434:

<comment>This removes `disableCertificateValidation` from a generated file, but the generator still emits it: `Java/libraries/jersey2/ApiClient.mustache` wraps the method in `{{#generateInsecureTlsHook}}`, and `JavaClientCodegen.java` defaults `generateInsecureTlsHook` to `true`. The config that generates this sample (`bin/configs/java-jersey2-8.yaml`) does not set `generateInsecureTlsHook: false`, so regenerating the sample (which CI does and compares against HEAD) restores the method and flags this file as out of sync, reverting the removal. The removal belongs in the template and/or config flag, not a hand edit of the generated sample.</comment>

<file context>
@@ -1431,45 +1424,12 @@ protected void applyDebugSetting(ClientConfig clientConfig) {
-  }
-
   /**
    * <p>Build the response headers.</p>
    *
</file context>

[cubic-dev-ai]

P2: This doc row is auto-generated by config-help -g java-microprofile --format markdown, derived from the generator's cliOptions. generateInsecureTlsHook is still registered in JavaClientCodegen (line 287) and JavaMicroprofileServerCodegen extends JavaClientCodegen without removing it, so config-help for java-microprofile still lists the option. Removing the row by hand makes the checked-in doc drift from the actual config surface, and the next bin/utils/export_docs_generators.sh run (which CI expects to be clean) will re-add it. If the intent is to drop the option for microprofile, the generator must stop exposing it in JavaMicroprofileServerCodegen, not just edit the doc.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/generators/java-microprofile.md, line 59:

<comment>This doc row is auto-generated by `config-help -g java-microprofile --format markdown`, derived from the generator's `cliOptions`. `generateInsecureTlsHook` is still registered in `JavaClientCodegen` (line 287) and `JavaMicroprofileServerCodegen extends JavaClientCodegen` without removing it, so `config-help` for java-microprofile still lists the option. Removing the row by hand makes the checked-in doc drift from the actual config surface, and the next `bin/utils/export_docs_generators.sh` run (which CI expects to be clean) will re-add it. If the intent is to drop the option for microprofile, the generator must stop exposing it in `JavaMicroprofileServerCodegen`, not just edit the doc.</comment>

<file context>
@@ -56,7 +56,6 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |generateClientAsBean|For resttemplate, restclient and webclient, configure whether to create `ApiClient.java` and Apis clients as bean (with `@Component` annotation).| |false|
 |generateConstructorWithAllArgs|whether to generate a constructor for all arguments| |false|
-|generateInsecureTlsHook|Generate the ApiClient.disableCertificateValidation hook, which trusts all TLS certificates (default to true). Set to false to omit it, e.g. when static analysis flags the trust-all TrustManager it contains. Available on `jersey2`, `jersey3` libraries.| |true|
 |gradleProperties|Append additional Gradle properties to the gradle.properties file| |null|
 |groupId|groupId in generated pom.xml| |org.openapitools|
 |hideGenerationTimestamp|Hides the generation timestamp when files are generated.| |false|
</file context>

[cubic-dev-ai]

P2: Removing disableCertificateValidation from this generated ApiClient.java makes the committed sample inconsistent with the generator output. The jersey2 template still emits the method under {{#generateInsecureTlsHook}}, whose default is true (JavaClientCodegen.java:287,532-536), and bin/configs/java-jersey2-java8-localdatetime.yaml does not set generateInsecureTlsHook: false. Regenerating this sample (as the samples-verification CI step does) will restore the method and leave a non-clean git diff, failing CI. Either set generateInsecureTlsHook: false in that config, or keep the method in the sample.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/jersey2-java8-localdatetime/src/main/java/org/openapitools/client/ApiClient.java, line 1371:

<comment>Removing disableCertificateValidation from this generated ApiClient.java makes the committed sample inconsistent with the generator output. The jersey2 template still emits the method under {{#generateInsecureTlsHook}}, whose default is true (JavaClientCodegen.java:287,532-536), and bin/configs/java-jersey2-java8-localdatetime.yaml does not set generateInsecureTlsHook: false. Regenerating this sample (as the samples-verification CI step does) will restore the method and leave a non-clean git diff, failing CI. Either set generateInsecureTlsHook: false in that config, or keep the method in the sample.</comment>

<file context>
@@ -38,13 +38,6 @@
 import java.io.InputStream;
 
 import java.net.URI;
-import javax.net.ssl.SSLContext;
-import javax.net.ssl.TrustManager;
-import javax.net.ssl.X509TrustManager;
-import java.security.cert.X509Certificate;
-import java.security.KeyManagementException;
-import java.security.NoSuchAlgorithmException;
</file context>

[cubic-dev-ai]

P2: These 6 test files were removed from the .openapi-generator/FILES manifest but still exist in the sample and are not protected by .openapi-generator-ignore (it is empty). The manifest now disagrees with the sample contents, and the files carry the generator's auto-generated header, so a fresh regeneration will re-emit them and re-list them in FILES, producing a diff that fails the sample-verification CI check. If the tests are meant to be preserved as manually-maintained generated files, add them to .openapi-generator-ignore; otherwise delete them from the sample so FILES and disk stay in sync.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/webclient-springBoot4-jackson3-jspecify-optional-getters/.openapi-generator/FILES, line 47:

<comment>These 6 test files were removed from the .openapi-generator/FILES manifest but still exist in the sample and are not protected by .openapi-generator-ignore (it is empty). The manifest now disagrees with the sample contents, and the files carry the generator's auto-generated header, so a fresh regeneration will re-emit them and re-list them in FILES, producing a diff that fails the sample-verification CI check. If the tests are meant to be preserved as manually-maintained generated files, add them to .openapi-generator-ignore; otherwise delete them from the sample so FILES and disk stay in sync.</comment>

<file context>
@@ -44,9 +44,3 @@ src/main/java/org/openapitools/client/model/Foo.java
 src/main/java/org/openapitools/client/model/RequiredAndNullable.java
 src/main/java/org/openapitools/client/model/package-info.java
 src/main/java/org/openapitools/client/package-info.java
-src/test/java/org/openapitools/client/api/FileApiTest.java
-src/test/java/org/openapitools/client/api/FooApiTest.java
-src/test/java/org/openapitools/client/api/RequiredAndNullableApiTest.java
-src/test/java/org/openapitools/client/api/UploadApiTest.java
-src/test/java/org/openapitools/client/model/FileContentTest.java
-src/test/java/org/openapitools/client/model/RequiredAndNullableTest.java
</file context>

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/generators/elixir.md">

<violation number="1" location="docs/generators/elixir.md:27">
P3: This removes the documentation row for the `library` option, but `library` is still a registered, supported config option in ElixirClientCodegen (enum tesla/req, default tesla). Leaving a valid option undocumented misleads users and the row will be regenerated anyway by export_docs_generators.sh, which emits all cliOptions. Keep the row, or update the option description if that was the intent.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: This removes the documentation row for the library option, but library is still a registered, supported config option in ElixirClientCodegen (enum tesla/req, default tesla). Leaving a valid option undocumented misleads users and the row will be regenerated anyway by export_docs_generators.sh, which emits all cliOptions. Keep the row, or update the option description if that was the intent.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/generators/elixir.md, line 27:

<comment>This removes the documentation row for the `library` option, but `library` is still a registered, supported config option in ElixirClientCodegen (enum tesla/req, default tesla). Leaving a valid option undocumented misleads users and the row will be regenerated anyway by export_docs_generators.sh, which emits all cliOptions. Keep the row, or update the option description if that was the intent.</comment>

<file context>
@@ -24,7 +24,6 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |invokerPackage|The main namespace to use for all classes. e.g. Yay.Pets| |null|
 |legacyDiscriminatorBehavior|Set to false for generators with better support for discriminators. (Python, Java, Go, PowerShell, C# have this enabled by default).|<dl><dt>**true**</dt><dd>The mapping in the discriminator includes descendent schemas that allOf inherit from self and the discriminator mapping schemas in the OAS document.</dd><dt>**false**</dt><dd>The mapping in the discriminator includes any descendent schemas that allOf inherit from self, any oneOf schemas, any anyOf schemas, any x-discriminator-values, and the discriminator mapping schemas in the OAS document AND Codegen validates that oneOf and anyOf schemas contain the required discriminator and throws an error if the discriminator is missing.</dd></dl>|true|
-|library|HTTP library template (sub-template) to use|<dl><dt>**tesla**</dt><dd>Tesla &gt;= 1.14 (https://github.com/elixir-tesla/tesla)</dd><dt>**req**</dt><dd>Req &gt;= 0.6.0 (excluding 0.7.0-0.7.2) (https://github.com/wojtekmach/req)</dd></dl>|tesla|
 |licenseHeader|The license header to prepend to the top of all source files.| |null|
 |packageName|Elixir package name (convention: lowercase).| |null|
 |prependFormOrBodyParameters|Add form or body parameters to the beginning of the parameter list.| |false|
</file context>