From e05e4a12b9d3dad4dfe860db9bf1a0b7692ff472 Mon Sep 17 00:00:00 2001
From: Chrimle <28791817+Chrimle@users.noreply.github.com>
Date: Wed, 11 Mar 2026 22:06:54 +0100
Subject: [PATCH] [Java][Spring] Insert Annotations to be `TYPE_USE` Compatible

Signed-off-by: Chrimle <28791817+Chrimle@users.noreply.github.com>
---
 .../java/spring/SpringCodegenTest.java        | 30 +++++++++++++++++++
 .../resources/3_0/spring/issue_23206.yaml     | 28 +++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 modules/openapi-generator/src/test/resources/3_0/spring/issue_23206.yaml

diff --git a/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java b/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java
index 032c192fac42..41e57915e5f2 100644
--- a/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java
+++ b/modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java
@@ -28,6 +28,7 @@
 import org.apache.commons.lang3.StringUtils;
 import org.assertj.core.api.Assertions;
 import org.assertj.core.api.MapAssert;
+import org.junit.jupiter.api.DisplayName;
 import org.openapitools.codegen.*;
 import org.openapitools.codegen.config.CodegenConfigurator;
 import org.openapitools.codegen.config.GlobalSettings;
@@ -6637,4 +6638,33 @@ public void shouldNotHaveDocumentationAnnotationWhenUsingLibrarySpringHttpInterf
         JavaFileAssert.assertThat(Paths.get(outputPath + "/src/main/java/org/openapitools/api/PetApi.java"))
                 .assertMethod("addPet").assertParameter("pet").assertParameterAnnotations().doesNotContainWithName("Parameter");
     }
+
+  @Test
+  @DisplayName("Testing Issue #23206: Support JSpecify with SchemaMappings")
+  public void testIssue23206() throws IOException {
+    final SpringCodegen codegen = new SpringCodegen();
+
+    codegen.setLibrary("spring-boot");
+
+    codegen.importMapping().put("org.springframework.lang.Nullable", "org.jspecify.annotations.Nullable");
+    codegen.schemaMapping().put("PersonCountValue", "a.b.c.PersonCountValue");
+
+    codegen.additionalProperties().put(OPENAPI_NULLABLE, "false");
+    codegen.additionalProperties().put(SKIP_DEFAULT_INTERFACE, "true");
+    codegen.additionalProperties().put(USE_SPRING_BOOT4, "true");
+    codegen.additionalProperties().put(USE_JACKSON_3, "true");
+    codegen.additionalProperties().put(USE_TAGS, "true");
+    codegen.additionalProperties().put(USE_BEANVALIDATION, "false");
+
+    final Map<String, File> files = generateFiles(codegen, "src/test/resources/3_0/spring/issue_23206.yaml");
+    final var javaFileAssert = JavaFileAssert.assertThat(files.get("MyDto.java"));
+
+    javaFileAssert
+        .hasImports("org.jspecify.annotations.Nullable")
+        .assertProperty("men");
+
+    // Should Fail without any changes to the mustache templates!
+    javaFileAssert.fileContains("private a.b.c.@Nullable PersonCountValue men;"); // Actual: private @Nullable a.b.c.PersonCountValue men;
+    javaFileAssert.fileContains("private a.b.c.@Nullable PersonCountValue women;"); // Actual: private @Nullable a.b.c.PersonCountValue women;
+  }
 }
diff --git a/modules/openapi-generator/src/test/resources/3_0/spring/issue_23206.yaml b/modules/openapi-generator/src/test/resources/3_0/spring/issue_23206.yaml
new file mode 100644
index 000000000000..6d448585c57b
--- /dev/null
+++ b/modules/openapi-generator/src/test/resources/3_0/spring/issue_23206.yaml
@@ -0,0 +1,28 @@
+openapi: "3.0.3"
+info:
+  title: Move Annotations in Generated POJOs
+  description: "Test Placement of Annotations, to allow TYPE_USE Annotations to compile correctly. See #23206"
+  version: 1.0.0
+
+paths:
+  /some/endpoint:
+    get:
+      responses:
+        "200":
+          description: OK
+
+components:
+  schemas:
+    MyDto:
+      type: object
+      properties:
+        men:
+          nullable: true
+          $ref: '#/components/schemas/PersonCountValue'
+        women:
+          nullable: true
+          $ref: '#/components/schemas/PersonCountValue'
+    PersonCountValue:
+      type: number
+      format: personCountValue
+      example: 1234