From 751ab5c7da469310c7a8a270ceba976c8377d727 Mon Sep 17 00:00:00 2001
From: timonrieger <mail@timonrieger.de>
Date: Thu, 26 Mar 2026 13:23:43 +0100
Subject: [PATCH] fix: preserve parent description when simplifying nullable
 anyOf/oneOf

---
 .../codegen/utils/ModelUtils.java             |  4 +++
 .../codegen/utils/ModelUtilsTest.java         | 33 +++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java
index a8f62b1b8331..9bae4fed18e8 100644
--- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java
+++ b/modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java
@@ -2268,6 +2268,10 @@ public static Schema simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(OpenAPI openA
         // if only one element left, simplify to just the element (schema)
         if (subSchemas.size() == 1) {
             Schema<?> subSchema = subSchemas.get(0);
+            // Preserve parent-level docs when nullable anyOf/oneOf collapses to a single child schema.
+            if (subSchema.getDescription() == null && schema.getDescription() != null) {
+                subSchema.setDescription(schema.getDescription());
+            }
             if (Boolean.TRUE.equals(schema.getNullable())) { // retain nullable setting
                 subSchema.setNullable(true);
             }
diff --git a/modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java b/modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java
index 48f1340cf137..906ace829bcb 100644
--- a/modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java
+++ b/modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java
@@ -27,6 +27,7 @@
 import org.testng.annotations.Test;
 
 import java.math.BigDecimal;
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;
 import java.util.List;
@@ -582,6 +583,38 @@ public void simplifyAnyOfWithOnlyOneNonNullSubSchemaKeepsReadOnlyWriteOnlyAttrib
         assertEquals(schema.get$ref(), "#/components/schemas/IntegerRef");
     }
 
+    @Test
+    public void simplifyOneOfAnyOfWithOnlyOneNonNullSubSchemaKeepsParentDescription() {
+        OpenAPI openAPI = new OpenAPI();
+
+        Schema anyOfParent = new Schema().description("Access token");
+        anyOfParent.setAnyOf(new ArrayList<>(Arrays.asList(
+                new StringSchema(),
+                new Schema<>().type("null")
+        )));
+        Schema anyOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, anyOfParent, anyOfParent.getAnyOf());
+        assertEquals(anyOfSchema.getDescription(), "Access token");
+
+        Schema oneOfParent = new Schema().description("Expires at");
+        oneOfParent.setOneOf(new ArrayList<>(Arrays.asList(
+                new IntegerSchema(),
+                new Schema<>().type("null")
+        )));
+        Schema oneOfSchema = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(openAPI, oneOfParent, oneOfParent.getOneOf());
+        assertEquals(oneOfSchema.getDescription(), "Expires at");
+
+        Schema anyOfParentWithChildDescription = new Schema().description("Parent description");
+        anyOfParentWithChildDescription.setAnyOf(new ArrayList<>(Arrays.asList(
+                new StringSchema().description("Child description"),
+                new Schema<>().type("null")
+        )));
+        Schema anyOfSchemaWithChildDescription = ModelUtils.simplifyOneOfAnyOfWithOnlyOneNonNullSubSchema(
+                openAPI,
+                anyOfParentWithChildDescription,
+                anyOfParentWithChildDescription.getAnyOf());
+        assertEquals(anyOfSchemaWithChildDescription.getDescription(), "Child description");
+    }
+
     @Test
     public void isNullTypeSchemaTest() {
         OpenAPI openAPI = TestUtils.parseSpec("src/test/resources/3_0/null_schema_test.yaml");