fix: preserve parent description when simplifying nullable anyOf/oneOf (#23361)

Author: timonrieger

modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java

@@ -2300,6 +2300,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);
             }

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");