[BUG][JAVA] useJspecify=true: java/restclient and java/webclient ApiClient support class still imports jakarta.annotation.Nullable

[austek]

[BUG][JAVA] useJspecify=true: java/restclient and java/webclient ApiClient support class still imports jakarta.annotation.Nullable

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?
• [Optional] Sponsorship to speed up the bug fix or feature request

Description

With useJspecify=true, the java generator correctly emits org.jspecify.annotations.Nullable
on models and API code, but the generated ApiClient support class for the
restclient and webclient libraries still emits:

import jakarta.annotation.Nullable;   // (or javax.annotation.Nullable when useJakartaEe=false)

used by createDefaultMapper(@Nullable DateFormat dateFormat).

The import is hardcoded in the template and is not guarded by useJspecify, so the generated
client mixes JSpecify everywhere except ApiClient, which keeps the jakarta/javax annotation.
For projects that enforce "JSpecify only" (e.g. an ArchUnit/NullAway rule banning
jakarta.annotation/javax.annotation/org.springframework.lang nullness annotations), this
single import breaks the build / trips the rule and must currently be patched out by hand.

openapi-generator version

7.23.0 (also present on master). The useJspecify option was introduced in 7.22.0 via #23256.

OpenAPI declaration file content or url

Any spec generated with the java generator and the restclient (or webclient) library —
the ApiClient support class is library-level, independent of the spec. Minimal config:

generatorName: java
library: restclient
additionalProperties:
  useJakartaEe: "true"
  useJspecify: "true"

Generation Steps

openapi-generator-cli generate \
  -g java --library restclient \
  -i petstore.yaml -o out \
  --additional-properties=useJakartaEe=true,useJspecify=true

Actual output

out/src/main/java/.../ApiClient.java:

import jakarta.annotation.Nullable;
...
public static JsonMapper createDefaultMapper(@Nullable DateFormat dateFormat) { ... }

Expected output

Under useJspecify=true, the import should resolve to JSpecify, consistent with the rest of the
generated sources:

import org.jspecify.annotations.Nullable;

Root cause

Java/libraries/restclient/ApiClient.mustache (line 82) and
Java/libraries/webclient/ApiClient.mustache (line 85) hardcode:

import {{javaxPackage}}.annotation.Nullable;

with no {{#useJspecify}} guard. #23256 wired JSpecify through the model/API codegen
(AbstractJavaCodegen#applyJspecify / addNullableImportForOperation) and the JavaSpring
nullableAnnotation partial, but the java-library ApiClient support templates were not
updated. @Nullable is used as a simple name in both files, so only the import line needs to be
made conditional. (Other java libraries' ApiClient.mustache do not import Nullable and are
unaffected.)

[siudeks]

Closing this issue is problematic for my use case, so I’d like to clarify the requirement and suggest a concrete solution.

In my project, these annotations serve two different purposes:

jakarta.* annotations are used at runtime (e.g., serialization/deserialization and Jakarta-based validation),
org.jspecify.* annotations are used for static analysis at compile time (NullAway / architecture rules / nullability contracts).
Because of that, I need a way to generate both annotation sets at the same time. They are not inherently in conflict, since they operate at different layers:

Jakarta helps validate and process real data at runtime,
JSpecify enforces nullability contracts at compile time,
together they provide end-to-end safety (runtime data correctness + compile-time null-safety guarantees).
With the current behavior (effectively forcing one annotation system), this mixed workflow regresses.

Proposed solution
When both flags are enabled:

useJakartaEe=true
useJspecify=true
the generator should support a combined mode and generate both related annotations correctly, instead of treating them as mutually exclusive.

Possible implementation options:

honor both switches directly as “emit both” behavior,
or introduce an explicit strategy option such as nullabilityAnnotations=jspecify|jakarta|both,
or at least add a dedicated switch for ApiClient / support classes so mixed scenarios remain supported.
I’m happy to help refine the expected behavior and validate a proposed implementation on a real project.