[BUG][Spring] useJspecify=true can emit @Nullable without importing org.jspecify.annotations.Nullable

[ThalysGomes]

Description

When using the spring generator with useJspecify=true, generated API interfaces can contain @Nullable in parameter types/signatures without the required import:

import org.jspecify.annotations.Nullable;

This causes compilation failures in generated sources.

Confirmed affected case

Confirmed with:

• generator: spring
• library: spring-cloud
• options:
  • useJspecify=true
  • openApiNullable=false
  • useSpringBoot3=true

Generated output example

Generated Spring API interfaces can contain method parameters such as:

ResponseEntity<APIProxyDeploymentDetailsEnv> getAPIProxyDeploymentEnv(
    @Parameter(name = "org_name", description = "Organization name.", required = true, in = ParameterIn.PATH)
    @PathVariable("org_name")
    @Nullable String orgName,
    @Parameter(name = "env_name", description = "Environment name.", required = true, in = ParameterIn.PATH)
    @PathVariable("env_name")
    String envName,
    @Parameter(name = "api_name", description = "API proxy name.", required = true, in = ParameterIn.PATH)
    @PathVariable("api_name")
    String apiName
);

but the generated imports do not include:

import org.jspecify.annotations.Nullable;

This causes compilation errors like:

error: cannot find symbol
  symbol:   class Nullable

Upstream source inspection

While investigating the generator source, this appears to be in the shared Spring parameter/import path rather than in any project-specific template customization.

Relevant files in this repository:

• modules/openapi-generator/src/main/resources/JavaSpring/pathParams.mustache
• modules/openapi-generator/src/main/resources/JavaSpring/queryParams.mustache
• modules/openapi-generator/src/main/resources/JavaSpring/headerParams.mustache
• modules/openapi-generator/src/main/resources/JavaSpring/bodyParams.mustache
• modules/openapi-generator/src/main/resources/JavaSpring/cookieParams.mustache
• modules/openapi-generator/src/main/resources/JavaSpring/nullableAnnotation.mustache
• modules/openapi-generator/src/main/resources/JavaSpring/optionalDataType.mustache
• modules/openapi-generator/src/main/resources/JavaSpring/api.mustache
• modules/openapi-generator/src/main/resources/JavaSpring/libraries/spring-http-interface/api.mustache
• modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java
• modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java

In particular:

• SpringCodegen sets the mapping:

importMapping.put("Nullable", useJspecify ? "org.jspecify.annotations.Nullable" : "org.springframework.lang.Nullable");

• AbstractJavaCodegen.applyJspecify() also maps Nullable to org.jspecify.annotations.Nullable.
• AbstractJavaCodegen.addNullableImportForOperation(...) adds the Nullable import only when a parameter matches notRequiredOrIsNullable().
• AbstractJavaCodegen.JSpecifyNullableLambda / jSpecifyDatatype are involved in moving @Nullable into the type position.

That means there is at least one Spring generation path where @Nullable reaches the rendered signature but codegenOperation.imports does not receive Nullable.

Scope / likely affected variants

This is confirmed for spring + library=spring-cloud.

From source inspection, the same shared Spring parameter partials are reused by other Spring generator variants, so it is worth validating at least:

• spring + library=spring-boot
• spring + library=spring-http-interface
• delegate/interface generation paths using JavaSpring/api.mustache

I am not claiming all of those are confirmed broken, only that they appear to share the same template path and should be checked.

Expected behavior

Whenever @Nullable is emitted and useJspecify=true, the generated file should also include:

import org.jspecify.annotations.Nullable;

Actual behavior

@Nullable appears in generated Spring API signatures, but the corresponding import is sometimes missing.

Workaround

As a workaround, I post-process generated files and inject the missing import whenever @Nullable is present but the import is missing:

// OAG spring-cloud template emits @Nullable on required object-type parameters but
// doesn't always add the import when useJspecify=true (known generator bug).
// Post-process to ensure the import is present wherever @Nullable is used.
fileTree(layout.buildDirectory.dir("generated-code")).matching {
    include '**/*.java'
}.each { file ->
    def text = file.text
    if (text.contains('@Nullable')
            && !text.contains('import org.jspecify.annotations.Nullable;')) {
        file.text = text.replaceFirst(
            '(package [^;]+;\\s*\\n)',
            '$1import org.jspecify.annotations.Nullable;\n'
        )
    }
}

Version

Observed with:

• OpenAPI Generator: 7.22.0

Suggested fix

Please review the Spring generator import registration for JSpecify-enabled parameter rendering and ensure that every code path that can emit @Nullable also registers Nullable in the operation/class imports.

[jpfinne]

@ThalysGomes please retry with 7.23.0-SNAPSHOT or use the mustache template in #23649

[SubhamAshok]

I tested this on latest master (7.25.0-SNAPSHOT, built locally) with the reported config: spring generator, library=spring-cloud, useJspecify=true, openApiNullable=false, useSpringBoot3=true.

The reported bug is fixed. Optional params get @nullable and the import is present. Required path params no longer get a wrong @nullable. The 7.23.0 problem came from pathParams.mustache reading stale lambda state, and #23649 fixed that.

While checking, I found one leftover spot with the same root cause. In jspecify mode, toIndentedString(Object o) in pojo.mustache loses its @nullable because nothing re-inserts it after the lambda strips it. The model package is @NullMarked, and toString() passes nullable fields into it, so NullAway and IntelliJ flag every generated model. Without jspecify the annotation is generated fine. The constructor and fluent setter cases are already covered by #24563, this one is not.

I have a one line fix with a test. I will open a PR unless you would rather include it in #24563.

[jpfinne]

@SubhamAshok thanks.

I'm busy with a bigger PR that include several fixes for jspecify. Default handling , toIndentedString, openapiNullable, useOptional, allArgConstructors... #24563