[java] [Spring] useJspecify for java clients and spring generator#23256
[java] [Spring] useJspecify for java clients and spring generator#23256jpfinne wants to merge 9 commits intoOpenAPITools:masterfrom
Conversation
There was a problem hiding this comment.
12 issues found across 211 files
Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.
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/restclient-springBoot4-jackson3-jspecify/README.md">
<violation number="1" location="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify/README.md:96">
P1: The generated README example uses `new java.time.Instant()` which is invalid Java code that will not compile. `java.time.Instant` has private constructors and can only be instantiated via factory methods like `Instant.now()` or `Instant.parse()`. This makes the "Getting Started" example uncompilable for users who copy it.</violation>
<violation number="2" location="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify/README.md:102">
P1: The README example catches `HttpStatusCodeException` without importing it. The generated API code throws `RestClientResponseException`, but the README example uses a different exception type that isn't imported. This will cause a compilation error when developers try to use the example code.</violation>
</file>
<file name="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/model/AbstractOpenApiSchema.java">
<violation number="1" location="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/model/AbstractOpenApiSchema.java:114">
P2: Method's Object parameter should be annotated @Nullable to correctly advertise that null is accepted (as confirmed by the null check in the body).</violation>
</file>
<file name="samples/client/petstore/java/native-jackson3-jspecify/git_push.sh">
<violation number="1" location="samples/client/petstore/java/native-jackson3-jspecify/git_push.sh:53">
P2: The script hardcodes `master` branch which breaks for repositories with `main` or other default branch names</violation>
</file>
<file name="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify/.travis.yml">
<violation number="1" location="samples/client/petstore/java/restclient-springBoot4-jackson3-jspecify/.travis.yml:12">
P1: Travis CI JDK matrix is incompatible with Spring Boot 4 sample - configured JDKs (8-12) are below the Java 17 minimum requirement</violation>
</file>
<file name="samples/client/petstore/java/native-jackson3-jspecify/README.md">
<violation number="1" location="samples/client/petstore/java/native-jackson3-jspecify/README.md:88">
P2: Generated README uses invalid `Instant` construction. The sample code uses `new java.time.Instant()` which fails to compile because `java.time.Instant` is an immutable value type with no public constructors. Use factory methods like `Instant.now()` or `Instant.parse(...)` instead.</violation>
</file>
<file name="samples/client/petstore/java/native-jackson3-jspecify/pom.xml">
<violation number="1" location="samples/client/petstore/java/native-jackson3-jspecify/pom.xml:5">
P1: Maven coordinates collide with existing non-JSpecify sample. Both samples use identical groupId/artifactId/version (org.openapitools:petstore-native-jackson3:1.0.0), causing artifact collisions when both are installed to the local Maven repository.</violation>
</file>
<file name="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/RFC3339InstantDeserializer.java">
<violation number="1" location="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/RFC3339InstantDeserializer.java:32">
P1: Custom parsing lost during Jackson contextualization - subclass must override withDateFormat/withLeniency/withShape to preserve RFC3339 space-handling behavior</violation>
</file>
<file name="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/Configuration.java">
<violation number="1" location="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/Configuration.java:57">
P2: Changing the `ApiClient` factory after the default client has been initialized has no effect because the cached singleton is never cleared. The `setApiClientFactory` method should invalidate the cached `defaultApiClient` or the factory change will be silently ignored once the client is lazily initialized.</violation>
</file>
<file name="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/model/Foo.java">
<violation number="1" location="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/model/Foo.java:76">
P1: Required property `requiredDt` is exposed as non-null (no @Nullable annotation under @NullMarked package) but can be left null by the generated no-arg constructor and builder's build() method without validation. This creates a JSpecify contract violation where callers trusting the non-null type may encounter NPE when dereferencing getRequiredDt(). The toUrlQueryString() method's null check for getRequiredDt() confirms this is a known gap in the code generation.</violation>
</file>
<file name="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/api/DefaultApi.java">
<violation number="1" location="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/api/DefaultApi.java:274">
P1: The `dtCookie` parameter is defined in the OpenAPI spec and exposed in the API method signatures, but it is never added to the HTTP request. The request builder accepts the parameter but ignores it instead of adding it as a Cookie header.</violation>
<violation number="2" location="samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/api/DefaultApi.java:401">
P1: Optional file parameter `_file` marked as `@Nullable` is passed unconditionally to `addBinaryBody()` without null checking. This will cause a runtime exception when null is passed, violating the advertised nullable contract. The fix should wrap the `addBinaryBody()` call with a null check: `if (_file != null) { multiPartBuilder.addBinaryBody("file", _file); hasFiles = true; }`</violation>
</file>
Since this is your first cubic review, here's how it works:
- cubic automatically reviews your code and comments on bugs and improvements
- Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
- Add one-off context when rerunning by tagging
@cubic-dev-aiwith guidance or docs links (includingllms.txt) - Ask questions if you need clarification on any suggestion
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| try { | ||
| Foo result = apiInstance.fooDtParamGet(dtParam, dtQuery, dtCookie); | ||
| System.out.println(result); | ||
| } catch (HttpStatusCodeException e) { |
There was a problem hiding this comment.
P1: The README example catches HttpStatusCodeException without importing it. The generated API code throws RestClientResponseException, but the README example uses a different exception type that isn't imported. This will cause a compilation error when developers try to use the example code.
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/README.md, line 102:
<comment>The README example catches `HttpStatusCodeException` without importing it. The generated API code throws `RestClientResponseException`, but the README example uses a different exception type that isn't imported. This will cause a compilation error when developers try to use the example code.</comment>
<file context>
@@ -0,0 +1,142 @@
+ try {
+ Foo result = apiInstance.fooDtParamGet(dtParam, dtQuery, dtCookie);
+ System.out.println(result);
+ } catch (HttpStatusCodeException e) {
+ System.err.println("Exception when calling DefaultApi#fooDtParamGet");
+ System.err.println("Status code: " + e.getStatusCode().value());
</file context>
| defaultClient.setBasePath("http://localhost"); | ||
|
|
||
| DefaultApi apiInstance = new DefaultApi(defaultClient); | ||
| java.time.Instant dtParam = new java.time.Instant(); // java.time.Instant | |
There was a problem hiding this comment.
P1: The generated README example uses new java.time.Instant() which is invalid Java code that will not compile. java.time.Instant has private constructors and can only be instantiated via factory methods like Instant.now() or Instant.parse(). This makes the "Getting Started" example uncompilable for users who copy it.
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/README.md, line 96:
<comment>The generated README example uses `new java.time.Instant()` which is invalid Java code that will not compile. `java.time.Instant` has private constructors and can only be instantiated via factory methods like `Instant.now()` or `Instant.parse()`. This makes the "Getting Started" example uncompilable for users who copy it.</comment>
<file context>
@@ -0,0 +1,142 @@
+ defaultClient.setBasePath("http://localhost");
+
+ DefaultApi apiInstance = new DefaultApi(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>
| java.time.Instant dtParam = new java.time.Instant(); // java.time.Instant | | |
| + java.time.Instant dtParam = java.time.Instant.now(); // java.time.Instant | |
| - openjdk11 | ||
| - openjdk10 | ||
| - openjdk9 | ||
| - openjdk8 |
There was a problem hiding this comment.
P1: Travis CI JDK matrix is incompatible with Spring Boot 4 sample - configured JDKs (8-12) are below the Java 17 minimum requirement
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/.travis.yml, line 12:
<comment>Travis CI JDK matrix is incompatible with Spring Boot 4 sample - configured JDKs (8-12) are below the Java 17 minimum requirement</comment>
<file context>
@@ -0,0 +1,22 @@
+ - openjdk11
+ - openjdk10
+ - openjdk9
+ - openjdk8
+before_install:
+ # ensure gradlew has proper permission
</file context>
| xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> | ||
| <modelVersion>4.0.0</modelVersion> | ||
| <groupId>org.openapitools</groupId> | ||
| <artifactId>petstore-native-jackson3</artifactId> |
There was a problem hiding this comment.
P1: Maven coordinates collide with existing non-JSpecify sample. Both samples use identical groupId/artifactId/version (org.openapitools:petstore-native-jackson3:1.0.0), causing artifact collisions when both are installed to the local Maven repository.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3-jspecify/pom.xml, line 5:
<comment>Maven coordinates collide with existing non-JSpecify sample. Both samples use identical groupId/artifactId/version (org.openapitools:petstore-native-jackson3:1.0.0), causing artifact collisions when both are installed to the local Maven repository.</comment>
<file context>
@@ -0,0 +1,268 @@
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.openapitools</groupId>
+ <artifactId>petstore-native-jackson3</artifactId>
+ <packaging>jar</packaging>
+ <name>petstore-native-jackson3</name>
</file context>
| <artifactId>petstore-native-jackson3</artifactId> | |
| <artifactId>petstore-native-jackson3-jspecify</artifactId> |
| import tools.jackson.databind.ext.javatime.deser.InstantDeserializer; | ||
|
|
||
| @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen", comments = "Generator version: 7.21.0-SNAPSHOT") | ||
| public class RFC3339InstantDeserializer<T extends Temporal> extends InstantDeserializer<T> { |
There was a problem hiding this comment.
P1: Custom parsing lost during Jackson contextualization - subclass must override withDateFormat/withLeniency/withShape to preserve RFC3339 space-handling behavior
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/RFC3339InstantDeserializer.java, line 32:
<comment>Custom parsing lost during Jackson contextualization - subclass must override withDateFormat/withLeniency/withShape to preserve RFC3339 space-handling behavior</comment>
<file context>
@@ -0,0 +1,100 @@
+import tools.jackson.databind.ext.javatime.deser.InstantDeserializer;
+
+@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen", comments = "Generator version: 7.21.0-SNAPSHOT")
+public class RFC3339InstantDeserializer<T extends Temporal> extends InstantDeserializer<T> {
+ private static final long serialVersionUID = 1L;
+ private final static boolean DEFAULT_NORMALIZE_ZONE_ID = DateTimeFeature.NORMALIZE_DESERIALIZED_ZONE_ID.enabledByDefault();
</file context>
| } | ||
| } | ||
|
|
||
| private HttpRequest.Builder fooDtParamGetRequestBuilder( java.time.@Nullable Instant dtParam, java.time.@Nullable Instant dtQuery, java.time.@Nullable Instant dtCookie, Map<String, String> headers) throws ApiException { |
There was a problem hiding this comment.
P1: The dtCookie parameter is defined in the OpenAPI spec and exposed in the API method signatures, but it is never added to the HTTP request. The request builder accepts the parameter but ignores it instead of adding it as a Cookie header.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/api/DefaultApi.java, line 274:
<comment>The `dtCookie` parameter is defined in the OpenAPI spec and exposed in the API method signatures, but it is never added to the HTTP request. The request builder accepts the parameter but ignores it instead of adding it as a Cookie header.</comment>
<file context>
@@ -0,0 +1,445 @@
+ }
+ }
+
+ private HttpRequest.Builder fooDtParamGetRequestBuilder( java.time.@Nullable Instant dtParam, java.time.@Nullable Instant dtQuery, java.time.@Nullable Instant dtCookie, Map<String, String> headers) throws ApiException {
+
+ HttpRequest.Builder localVarRequestBuilder = HttpRequest.newBuilder();
</file context>
| return o.toString().replace("\n", "\n "); | ||
| } | ||
|
|
||
| public boolean equals(Object o) { |
There was a problem hiding this comment.
P2: Method's Object parameter should be annotated @nullable to correctly advertise that null is accepted (as confirmed by the null check in the body).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/model/AbstractOpenApiSchema.java, line 114:
<comment>Method's Object parameter should be annotated @Nullable to correctly advertise that null is accepted (as confirmed by the null check in the body).</comment>
<file context>
@@ -0,0 +1,147 @@
+ return o.toString().replace("\n", "\n ");
+ }
+
+ public boolean equals(Object o) {
+ if (this == o) {
+ return true;
</file context>
| public boolean equals(Object o) { | |
| public boolean equals(@Nullable Object o) { |
|
|
||
| fi | ||
|
|
||
| git pull origin master |
There was a problem hiding this comment.
P2: The script hardcodes master branch which breaks for repositories with main or other default branch names
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3-jspecify/git_push.sh, line 53:
<comment>The script hardcodes `master` branch which breaks for repositories with `main` or other default branch names</comment>
<file context>
@@ -0,0 +1,57 @@
+
+fi
+
+git pull origin master
+
+# Pushes (Forces) the changes in the local repository up to the remote repository
</file context>
| // Configure clients using the `defaultClient` object, such as | ||
| // overriding the host and port, timeout, etc. | ||
| DefaultApi apiInstance = new DefaultApi(defaultClient); | ||
| java.time.Instant dtParam = new java.time.Instant(); // java.time.Instant | |
There was a problem hiding this comment.
P2: Generated README uses invalid Instant construction. The sample code uses new java.time.Instant() which fails to compile because java.time.Instant is an immutable value type with no public constructors. Use factory methods like Instant.now() or Instant.parse(...) instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3-jspecify/README.md, line 88:
<comment>Generated README uses invalid `Instant` construction. The sample code uses `new java.time.Instant()` which fails to compile because `java.time.Instant` is an immutable value type with no public constructors. Use factory methods like `Instant.now()` or `Instant.parse(...)` instead.</comment>
<file context>
@@ -0,0 +1,137 @@
+ // Configure clients using the `defaultClient` object, such as
+ // overriding the host and port, timeout, etc.
+ DefaultApi apiInstance = new DefaultApi(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>
| java.time.Instant dtParam = new java.time.Instant(); // java.time.Instant | | |
| java.time.Instant dtParam = java.time.Instant.now(); // java.time.Instant | |
| /** | ||
| * set the callback used to create new ApiClient objects | ||
| */ | ||
| public static void setApiClientFactory(Supplier<ApiClient> factory) { |
There was a problem hiding this comment.
P2: Changing the ApiClient factory after the default client has been initialized has no effect because the cached singleton is never cleared. The setApiClientFactory method should invalidate the cached defaultApiClient or the factory change will be silently ignored once the client is lazily initialized.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/java/native-jackson3-jspecify/src/main/java/org/openapitools/client/Configuration.java, line 57:
<comment>Changing the `ApiClient` factory after the default client has been initialized has no effect because the cached singleton is never cleared. The `setApiClientFactory` method should invalidate the cached `defaultApiClient` or the factory change will be silently ignored once the client is lazily initialized.</comment>
<file context>
@@ -0,0 +1,63 @@
+ /**
+ * set the callback used to create new ApiClient objects
+ */
+ public static void setApiClientFactory(Supplier<ApiClient> factory) {
+ apiClientFactory = Objects.requireNonNull(factory);
+ }
</file context>
|
|
||
| protected void applyJspecify() { | ||
| writePropertyBack("nullableAnnotation", "@org.jspecify.annotations.Nullable"); | ||
| writePropertyBack("nonNullAnnotation", "@NonNull"); |
There was a problem hiding this comment.
no need for fully-qualified name?
| jSpecifyNullableLambda.keptNullable = false; | ||
| int idx = dataType.lastIndexOf('.'); | ||
| if (idx > 0) { | ||
| // generate declareation like java.time.@Nullable Timestamp |
There was a problem hiding this comment.
| // generate declareation like java.time.@Nullable Timestamp | |
| // generate declaration like java.time.@Nullable Timestamp |
| super.applyJspecify(); | ||
| addPackagInfoSupportingFiles(); | ||
| importMapping.put("Nullable", "org.jspecify.annotations.Nullable"); | ||
| jSpecifyNullableLambda.setNullableAnnotation("@" + additionalProperties.get(JAVAX_PACKAGE) + ".annotation.Nullable"); |
There was a problem hiding this comment.
Not sure if I understand why javax/jakarta should be used here? Because I did not see that we set this JAVAX_PACKAGE to be jspecify... but maybe I missed something
| writePropertyBack("nonNullAnnotation", "@jakarta.annotation.Nonnull"); | ||
| } | ||
|
|
||
| protected void applyJspecify() { |
There was a problem hiding this comment.
no need to set the JAVAX_PACKAGE to jspecify?
Add JSpecify in Spring and multiple java generators.
Fixes #23206
PR checklist
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.
master(upcoming7.x.0minor release - breaking changes with fallbacks),8.0.x(breaking changes without fallbacks)"fixes #123"present in the PR description)java:
@cachescrubber (2022/02) @welshm (2022/02) @MelleD (2022/02) @atextor (2022/02) @manedev79 (2022/02) @javisst (2022/02) @borsch (2022/02) @banlevente (2022/02) @Zomzog (2022/09) @martin-mfg (2023/08)
Spring:
@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)
Summary by cubic
Adds
useJspecifyto Java clients (native, restclient, resttemplate, webclient) and Spring (Boot/Cloud/HTTP interface) to opt into JSpecify nullness. Generated code defaults to non-null with@org.jspecify.annotations.NullMarkedand uses@org.jspecify.annotations.Nullablewhere needed; adds config presets and samples to showcase usage with Jackson 3 and Spring Boot 4.New Features
useJspecifyoption for Java clients and Spring; generatespackage-info.javawith@org.jspecify.annotations.NullMarkedinapi/invoker/modelpackages and mapsNullabletoorg.jspecify.annotations.Nullable(e.g., SpringNativeWebRequestfield and constructor param).@Nonnullunder@NullMarked; validated supported client libraries; refreshed generator docs for Java and Spring.bin/configs/*-jspecify.yamland generated sample projects for each supported Java client and Spring Boot to demonstrateuseJspecify.Dependencies
useJspecify: true, generated POMs includeorg.jspecify:jspecify:1.0.0across Java client libraries and Spring libraries.Written for commit cca147d. Summary will update on new commits.