[BUG] [JAVA] [SPRING] Impossible to use JSpecify with SchemaMappings

[felldo]

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 (example)

Description

The generated DTO looks something like this (simplified). The issue is that JSpecify's @Nullable cannot be placed before a fully qualified type name. The annotation must appear directly before the simple type name.
When the OpenAPI generator uses schema mappings, it references types by their fully qualified name instead of adding an import, which makes @Nullable placement invalid. This affects all usages of the type like fields, getters, setters, and constructors.
The fix would be to have the generator add proper imports and use simple type names instead. This would work in most cases, but breaks down if two schema-mapped types share the same simple name, then the generator would need to fall back to fully qualified names for one of them, reintroducing the problem.

public class MyDto implements Serializable {
  
  private static final long serialVersionUID = 1L;
  
  private @Nullable a.b.c.PersonCountValue men; // Doesn't work, current behavior
  
  private a.b.c.@Nullable PersonCountValue women; // Works
  
}

[ERROR] /path/a/b/c/MyDto.java type annotation @org.jspecify.annotations.Nullable is not expected here

openapi-generator version

<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>7.20.0</version>

OpenAPI declaration file content or url

my-api-specification.yaml

components:
  schemas:
    MyDto:
      type: object
      properties:
        men:
          $ref: '#/components/schemas/PersonCountValue'
        women:
          $ref: '#/components/schemas/PersonCountValue'
    PersonCountValue:
      type: number
      format: personCountValue
      example: 1234

my-api-config.yaml

schemaMappings:
  PersonCountValue: a.b.c.PersonCountValue

and then of course you need to set the config file in the generator with something like this

<configurationFile>
  ${project.basedir}/src/main/resources/static/my-api-config.yaml
</configurationFile>

Then no class for PersonCountValue will be generated but instead an existing class managed by yourself will be used for the type.

Generation Details

Using Java 25 with Maven

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>${openapi-generator-maven-plugin.version}</version>
  <configuration>
    <generatorName>spring</generatorName>
    <library>spring-boot</library>
    <generateSupportingFiles>false</generateSupportingFiles>
    <generateModelTests>false</generateModelTests>
    <importMappings>
      <importMapping>Nullable=org.jspecify.annotations.Nullable</importMapping>
    </importMappings>
    <generateApiTests>false</generateApiTests>
    <configOptions>
      <interfaceOnly>true</interfaceOnly>
      <oas3>true</oas3>
      <openApiNullable>false</openApiNullable>
      <serializableModel>true</serializableModel>
      <skipDefaultInterface>true</skipDefaultInterface>
      <useResponseEntity>true</useResponseEntity>
      <useSpringBoot4>true</useSpringBoot4>
      <useJackson3>true</useJackson3>
      <useSpringController>true</useSpringController>
      <useTags>true</useTags>
      <useBeanValidation>false</useBeanValidation>
    </configOptions>
  </configuration>
</plugin>

Steps to reproduce

Generate a Dto with a SchemaMapping type, which then will be written as package.name.Type instead of importing.

Suggest a fix

There needs to be a check, that when the type is not imported, that the annotation has to be right before the type and after the package name, like its shown in my example generated Dto above

[Chrimle]

I could have a look at it 👍

[Chrimle]

My opinion is that nullable annotations should be a completely separate configOption, so that users can pick between javax, jakarta, jspecify, etc... Anyways...

I wonder how simple this is... this issue stems from JSpecify's annotation:
@Target({ElementType.TYPE_USE})

[felldo]

I think its hard to handle all nullable annotations because they differ in how they are implemented. Like you said JSpecify uses TYPE_USE while springs own annotation uses METHOD, PARAMETER, FIELD.
But in the hindsight that eventually everyone moves to JSpecify as this is now what many people (that also represent large companies/frameworks) have agreed on to use it might be an idea to deprecate all other nullness annotations. The code will probably also become quite complex if you want to handle all different types of null annotations

[Chrimle]

I have been able to reproduce the issue on my fork. But, the provided examples here are incomplete.

The import mapping should be:
<importMapping>org.springframework.lang.Nullable=org.jspecify.annotations.Nullable</importMapping>

[felldo]

Why is it incomplete? I basically just copied this from my configuration after I found how to do this here.
Also the import mapping internally is done like this

[Chrimle]

Odd. Didn't work for me if I didn't qualify it. Anyways, seems like the following line needs to be updated:

openapi-generator/modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache

Line 87 in 8ef4a48

private {{>nullableAnnotation}}{{>nullableDataType}} {{name}}{{#isNullable}} = null{{/isNullable}}{{^isNullable}}{{#defaultValue}} = {{{.}}}{{/defaultValue}}{{/isNullable}};

However, it seems that the value available is the fully qualified class-name, but it would require the packageName and className to be separated in order to insert the annotation 🤔

[Chrimle]

Separate discussion entirely, but would it be desired to actually utilize the full extent of JSpecify? Like NullMarked etc.?

[felldo]

Separate discussion entirely, but would it be desired to actually utilize the full extent of JSpecify? Like NullMarked etc.?

The user should already be able to do this. When you include the generated sources from the generator in your sourceset, you can just add you own package-info.java file and annotate the package as @NullMarked

[Chrimle]

Well, I was thinking about the many other parameters, fields and variables 🤔 Like, using NotNull also?

[felldo]

I'm not sure what you mean.

After a second thought I think I have to withdraw my earlier statement.
For some reason I assumed annotating the root package info file in your project would apply the annotation to all sub packages, but this doesn't seem to be the case.
While you can add you own package-info file I think this can add a lot of manual overhead if you have to add this for every generated package. And this might also lead to missing package-info files if you extend your OpenApi files because the sources are auto generated. You would also have to maintain empty packages in your main project only containing package-info.java files which seems...weird.
I think usually you don't mix generated sources with packages you manage by yourself (because of possible conflicts with identical file names). One would most likely use a sub package. So it would make sense to generate a package-info.java with @NullMarked in the OpenApi generator.

[Chrimle]

Sure, but using NullMarked would suggest that we have evaluated nullness across the file/class, or as you're describing it - on package-level. My point was that the "nullness evaluation" has not been done (yet), and perhaps it could be done by annotating all these other types referenced in these generated classes 🤔 So, my question was a bit leading 😉 Would we like to do such an evaluation, and annotate all other types as well? (and use nullmarked/unmarked to minimize bloat of course)

(basically, GENERATE the appropriate annotations, rather than leaving it up for the user)

[Chrimle]

Or perhaps that will be near impossible, due to custom type-mappings? :(