change back resolveSubtypes to private, skip composeParentAsOneOf when @Schema(oneOf) is present instead of returning early

Author: ewaostrowska

CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+- Opt-in `oneOf` composition for `@JsonSubTypes` parents. Enable it with
+  `-Djson-subtypes-oneof` or `ModelResolver.jsonSubTypesOneOf = true`. When enabled,
+  a parent class with `@JsonSubTypes` gets a `oneOf` that lists its resolved subtypes,
+  and the subtypes keep their `allOf` reference to the parent. An explicit
+  `@Schema(oneOf = ...)` on the parent takes priority. The default is off, so the
+  generated schemas do not change unless you enable it. Use it for abstract classes and
+  interfaces. A concrete parent class is not listed in its own `oneOf`, so an instance of
+  the parent itself does not match the schema. Note: the result has a cycle
+  (`allOf` from subtype to parent, `oneOf` from parent to subtype). Some tools, such as
+  swagger-ui and openapi-generator, may not handle this shape well.
+
 ## [2.2.54] - 2026-08-18
 
 ### Fixed

modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/ModelResolver.java

@@ -1103,8 +1103,8 @@ public Schema resolve(AnnotatedType annotatedType, ModelConverterContext context
             });
 
             // Process the explicit @Schema(oneOf = ...) always. When the class also has @JsonSubTypes and
-            // jsonSubTypesOneOf is enabled, resolveSubtypes() returns early (explicit oneOf wins),
-            // so there is no conflict.
+            // jsonSubTypesOneOf is enabled, resolveSubtypes() skips composing the parent as oneOf
+            // (explicit oneOf wins), so there is no conflict.
             List<Class<?>> oneOfFiltered = Stream.of(oneOf)
                     .distinct()
                     .filter(c -> !this.shouldIgnoreClass(c))
@@ -2032,24 +2032,12 @@ protected boolean applyBeanValidatorAnnotationsNoGroups(Schema property, Annotat
         return modified;
     }
 
-    protected boolean resolveSubtypes(Schema model, BeanDescription bean, ModelConverterContext context, JsonView jsonViewAnnotation) {
+    private boolean resolveSubtypes(Schema model, BeanDescription bean, ModelConverterContext context, JsonView jsonViewAnnotation) {
         final List<NamedType> types = _intr().findSubtypes(_mapper.serializationConfig(), bean.getClassInfo());
         if (types == null || types.isEmpty()) {
             return false;
         }
 
-        // When opted in, an explicit @Schema(oneOf = ...) fully defines the polymorphism and must
-        // win over the @JsonSubTypes-derived composition. Skip the automatic allOf/oneOf
-        // composition to avoid the recursive allOf<->oneOf structure that is undesirable for
-        // many tools (see review on swagger-api/swagger-core#5320).
-        if (jsonSubTypesOneOf) {
-            io.swagger.v3.oas.annotations.media.Schema declaredSchema =
-                    AnnotationsUtils.getSchemaDeclaredAnnotation(bean.getClassInfo().getAnnotated());
-            if (declaredSchema != null && declaredSchema.oneOf().length > 0) {
-                return false;
-            }
-        }
-
         /**
          * Remove the current class from the child classes. This happens if @JsonSubTypes references
          * the annotated class as a subtype.
@@ -2120,7 +2108,13 @@ protected boolean resolveSubtypes(Schema model, BeanDescription bean, ModelConve
             }
         }
 
-        if (jsonSubTypesOneOf && !subtypeNames.isEmpty()) {
+        // An explicit @Schema(oneOf = ...) defines the parent's composition and wins over the
+        // @JsonSubTypes-derived one, which avoids a recursive allOf<->oneOf structure. Subtype
+        // handling is unaffected.
+        final io.swagger.v3.oas.annotations.media.Schema declaredSchema =
+                AnnotationsUtils.getSchemaDeclaredAnnotation(beanClass);
+        final boolean explicitOneOf = declaredSchema != null && declaredSchema.oneOf().length > 0;
+        if (jsonSubTypesOneOf && !explicitOneOf && !subtypeNames.isEmpty()) {
             composeParentAsOneOf(model, beanClass, subtypeNames.values(), context);
         }
         return count != 0;

modules/swagger-core/src/test/java/io/swagger/v3/core/resolving/JsonSubTypesAndSchemaOneOfTest.java

@@ -2,11 +2,8 @@
 
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
-import com.fasterxml.jackson.annotation.JsonView;
-import tools.jackson.databind.BeanDescription;
 import tools.jackson.databind.ObjectMapper;
 import io.swagger.v3.core.converter.AnnotatedType;
-import io.swagger.v3.core.converter.ModelConverterContext;
 import io.swagger.v3.core.converter.ModelConverterContextImpl;
 import io.swagger.v3.core.jackson.ModelResolver;
 import io.swagger.v3.oas.annotations.media.DiscriminatorMapping;
@@ -225,28 +222,6 @@ public void jsonSubTypesOnlyParentIsComposedIntoOneOfWhenOptedIn() {
         assertEquals(model.getOneOf().get(1).get$ref(), "#/components/schemas/PolymorphicSubtype2");
     }
 
-    @Test
-    public void extensionPointAllowsSubclassToRestorePreviousBehavior() {
-        ModelResolver.jsonSubTypesOneOf = true;
-        final ModelConverterContextImpl subclassContext =
-                new ModelConverterContextImpl(new RestorePreviousBehaviorModelResolver(new ObjectMapper()));
-        final Schema<?> restoredModel = subclassContext.resolve(new AnnotatedType(PolymorphicInterface.class));
-        assertFalse(restoredModel instanceof ComposedSchema && ((ComposedSchema) restoredModel).getOneOf() != null,
-                "the resolved parent must not be auto-converted to a oneOf ComposedSchema when resolveSubtypes() is overridden");
-    }
-
-    static class RestorePreviousBehaviorModelResolver extends ModelResolver {
-        RestorePreviousBehaviorModelResolver(ObjectMapper mapper) {
-            super(mapper);
-        }
-
-        @Override
-        protected boolean resolveSubtypes(Schema model, BeanDescription bean,
-                                          ModelConverterContext context, JsonView jsonViewAnnotation) {
-            return false;
-        }
-    }
-
     @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type", visible = true)
     @JsonSubTypes({
             @JsonSubTypes.Type(value = PolymorphicSubtype1.class, name = "subtype1"),
@@ -322,6 +297,16 @@ public void optInExplicitSchemaOneOfWinsOverJsonSubTypes() {
         assertEquals(model.getOneOf().size(), 2);
         assertEquals(model.getOneOf().get(0).get$ref(), "#/components/schemas/SubBean1");
         assertEquals(model.getOneOf().get(1).get$ref(), "#/components/schemas/SubBean2");
+
+        // subtype handling and discriminator are identical to the flag-off output
+        assertEquals(model.getDiscriminator().getPropertyName(), DISCRIMINATOR_PROPERTY_NAME);
+        assertEquals(model.getDiscriminator().getMapping().get(SUB_BEAN_1_NAME), "#/components/schemas/SubBean1");
+        assertEquals(model.getDiscriminator().getMapping().get(SUB_BEAN_2_NAME), "#/components/schemas/SubBean2");
+        for (String subName : new String[]{SUB_BEAN_1_NAME, SUB_BEAN_2_NAME}) {
+            final Schema<?> sub = context.getDefinedModels().get(subName);
+            assertTrue(sub instanceof ComposedSchema, subName + " must be composed");
+            assertEquals(((ComposedSchema) sub).getAllOf().get(0).get$ref(), "#/components/schemas/BaseBean");
+        }
     }
 
     @Test