@@ -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
 
@@ -94,6 +94,7 @@
 import java.lang.reflect.Type;
 import java.math.BigDecimal;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.HashMap;
@@ -122,6 +123,7 @@ public class ModelResolver extends AbstractModelConverter implements ModelConver
 
     public static final String SET_PROPERTY_OF_COMPOSED_MODEL_AS_SIBLING = "composed-model-properties-as-sibiling";
     public static final String SET_PROPERTY_OF_ENUMS_AS_REF = "enums-as-ref";
+    public static final String SET_PROPERTY_OF_JSON_SUBTYPES_ONE_OF = "json-subtypes-oneof";
 
     public static boolean composedModelPropertiesAsSibling = System.getProperty(SET_PROPERTY_OF_COMPOSED_MODEL_AS_SIBLING) != null;
 
@@ -138,6 +140,21 @@ public class ModelResolver extends AbstractModelConverter implements ModelConver
      */
     public static boolean enumsAsRef = System.getProperty(SET_PROPERTY_OF_ENUMS_AS_REF) != null;
 
+    /**
+     * Opt-in composition of a {@code @JsonSubTypes} parent into a self-referencing {@code oneOf}
+     * (the parent gets a {@code oneOf} to its subtypes while the subtypes keep {@code allOf} to the
+     * parent). This cyclic {@code allOf} &lt;-&gt; {@code oneOf} shape is off by default because several
+     * tools (swagger-ui, openapi-generator) dislike it; when enabled it can be turned on with
+     * {@code -Djson-subtypes-oneof} or by setting this field. When enabled, an explicit
+     * {@code @Schema(oneOf)} on the parent wins over the automatic composition; when disabled,
+     * the default (3.0.0) behavior applies unchanged.
+     * <p>
+     * Note that the resulting shape is also a validation cycle: a subtype must be valid against the
+     * parent ({@code allOf}) while the parent must be valid against one of its subtypes
+     * ({@code oneOf}), so strict validators may warn or reject it.
+     */
+    public static boolean jsonSubTypesOneOf = System.getProperty(SET_PROPERTY_OF_JSON_SUBTYPES_ONE_OF) != null;
+
     private boolean openapi31;
 
     private Schema.SchemaResolution schemaResolution = Schema.SchemaResolution.DEFAULT;
@@ -973,6 +990,15 @@ public Schema resolve(AnnotatedType annotatedType, ModelConverterContext context
             model.setDiscriminator(null);
         }
 
+        // When opted in, resolveSubtypes() may have replaced the parent model in the context with
+        // a oneOf ComposedSchema; re-read it so subsequent processing sees the composed schema.
+        if (jsonSubTypesOneOf && !type.isContainerType() && StringUtils.isNotBlank(name)) {
+            Schema updatedModel = context.getDefinedModels().get(name);
+            if (updatedModel != null) {
+                model = updatedModel;
+            }
+        }
+
         Discriminator discriminator = resolveDiscriminator(type, context);
         if (discriminator != null) {
             model.setDiscriminator(discriminator);
@@ -1076,6 +1102,9 @@ public Schema resolve(AnnotatedType annotatedType, ModelConverterContext context
 
             });
 
+            // Process the explicit @Schema(oneOf = ...) always. When the class also has @JsonSubTypes and
+            // 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))
@@ -2005,7 +2034,7 @@ protected boolean applyBeanValidatorAnnotationsNoGroups(Schema property, Annotat
 
     private boolean resolveSubtypes(Schema model, BeanDescription bean, ModelConverterContext context, JsonView jsonViewAnnotation) {
         final List<NamedType> types = _intr().findSubtypes(_mapper.serializationConfig(), bean.getClassInfo());
-        if (types == null) {
+        if (types == null || types.isEmpty()) {
             return false;
         }
 
@@ -2025,6 +2054,7 @@ private boolean resolveSubtypes(Schema model, BeanDescription bean, ModelConvert
 
         removeDuplicateSubTypes(types);
 
+        Map<Class<?>, String> subtypeNames = new LinkedHashMap<>();
         int count = 0;
         final Class<?> beanClass = bean.getClassInfo().getAnnotated();
         for (NamedType subtype : types) {
@@ -2076,10 +2106,39 @@ private boolean resolveSubtypes(Schema model, BeanDescription bean, ModelConvert
             Class<?> currentType = subtype.getType();
             if (StringUtils.isNotBlank(composedSchema.getName())) {
                 context.defineModel(composedSchema.getName(), composedSchema, new AnnotatedType().type(currentType), null);
+                subtypeNames.put(subtypeType, composedSchema.getName());
             }
+        }
 
+        // 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;
+return count != 0;
+    }
+
+    /**
+     * Converts the parent model into a {@code oneOf} of the resolved subtypes and replaces it in the
+     * context. This produces the cyclic {@code allOf <-> oneOf} shape and is therefore opt-in
+     * (see {@link #jsonSubTypesOneOf}).
+     */
+    private void composeParentAsOneOf(Schema model, Class<?> beanClass, Collection<String> subtypeNames, ModelConverterContext context) {
+        ComposedSchema oneOfSchema = ComposedSchema.from(model);
+        oneOfSchema.setOneOf(new ArrayList<>());
+
+        for (String subtypeName : subtypeNames) {
+            Schema refSchema = openapi31 ? new JsonSchema() : new Schema();
+            refSchema.$ref(Components.COMPONENTS_SCHEMAS_REF + subtypeName);
+            oneOfSchema.addOneOfItem(refSchema);
+        }
+
+        // Replace parent model in context with oneOf schema
+        context.defineModel(model.getName(), oneOfSchema, new AnnotatedType().type(beanClass), null);
     }
 
     private void removeSelfFromSubTypes(List<NamedType> types, BeanDescription bean) {
 
@@ -9,14 +9,12 @@
 import io.swagger.v3.oas.annotations.media.DiscriminatorMapping;
 import io.swagger.v3.oas.models.media.ComposedSchema;
 import io.swagger.v3.oas.models.media.Schema;
+import org.testng.annotations.AfterMethod;
 import org.testng.annotations.AfterTest;
 import org.testng.annotations.BeforeMethod;
 import org.testng.annotations.Test;
 
-import java.util.HashSet;
-import java.util.List;
 import java.util.Map;
-import java.util.Set;
 
 import static org.testng.Assert.*;
 
@@ -37,13 +35,20 @@ public class JsonSubTypesAndSchemaOneOfTest extends SwaggerTestBase {
     @BeforeMethod
     public void setup() {
         ModelResolver.composedModelPropertiesAsSibling = false;
+        ModelResolver.jsonSubTypesOneOf = false;
         ModelResolver modelResolver = new ModelResolver(new ObjectMapper());
         context = new ModelConverterContextImpl(modelResolver);
     }
 
+    @AfterMethod
+    public void resetJsonSubTypesOneOf() {
+        ModelResolver.jsonSubTypesOneOf = false;
+    }
+
     @AfterTest
     public void afterTest() {
         ModelResolver.composedModelPropertiesAsSibling = false;
+        ModelResolver.jsonSubTypesOneOf = false;
     }
 
     @Test
@@ -195,46 +200,180 @@ static class SubBean2InterfaceImplementor extends BaseBeanInterfaceImplementor {
     }
 
     @Test
-    public void duplicateJsonSubTypesEntriesAreDeduplicated() {
-        // Identical @JsonSubTypes entries (and Jackson's AnnotationIntrospectorPair) can report the
-        // same subtype more than once. When the parent is composed into a oneOf, each entry would
-        // otherwise become a repeated $ref.
-        //
-        // NOTE: on 3.0.0 alone the parent is not composed into a oneOf, so this test passes
-        // trivially. It only starts guarding against duplicates once the @JsonSubTypes -> oneOf
-        // composition lands (swagger-api/swagger-core#5320); with that change and without the
-        // dedup fix in resolveSubtypes(), the oneOf contains 3 entries instead of 2.
-        final Schema<?> model = context.resolve(new AnnotatedType(DuplicateSubTypesParent.class));
-
-        if (model instanceof ComposedSchema && ((ComposedSchema) model).getOneOf() != null) {
-            final List<Schema> oneOf = ((ComposedSchema) model).getOneOf();
-            assertEquals(oneOf.size(), 2, "duplicate @JsonSubTypes entries must be deduplicated");
-            final Set<String> refs = new HashSet<>();
-            for (Schema<?> item : oneOf) {
-                assertTrue(refs.add(item.get$ref()),
-                        "oneOf must not contain a repeated $ref: " + item.get$ref());
-            }
+    public void jsonSubTypesOnlyParentHasNoOneOfByDefault() {
+        // Default behavior (opt-in disabled): a @JsonSubTypes-only type is NOT composed into a oneOf,
+        // matching the 3.0.0 behavior.
+        ModelResolver.jsonSubTypesOneOf = false;
+        final Schema<?> model = context.resolve(new AnnotatedType(PolymorphicInterface.class));
+        assertNotNull(model);
+        assertTrue(model.getOneOf() == null || model.getOneOf().isEmpty(),
+                "with the default (opt-in disabled) the @JsonSubTypes-only parent must not be composed into a oneOf");
+    }
+
+    @Test
+    public void jsonSubTypesOnlyParentIsComposedIntoOneOfWhenOptedIn() {
+        ModelResolver.jsonSubTypesOneOf = true;
+        final Schema<?> model = context.resolve(new AnnotatedType(PolymorphicInterface.class));
+        assertTrue(model instanceof ComposedSchema,
+                "when opted in the @JsonSubTypes-only parent should be converted to a oneOf ComposedSchema");
+        assertNotNull(model.getOneOf());
+        assertEquals(model.getOneOf().size(), 2);
+        assertEquals(model.getOneOf().get(0).get$ref(), "#/components/schemas/PolymorphicSubtype1");
+        assertEquals(model.getOneOf().get(1).get$ref(), "#/components/schemas/PolymorphicSubtype2");
+    }
+
+    @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type", visible = true)
+    @JsonSubTypes({
+            @JsonSubTypes.Type(value = PolymorphicSubtype1.class, name = "subtype1"),
+            @JsonSubTypes.Type(value = PolymorphicSubtype2.class, name = "subtype2")
+    })
+    interface PolymorphicInterface {
+        String getType();
+        String getName();
+    }
+
+    static class PolymorphicSubtype1 implements PolymorphicInterface {
+        public String type = "subtype1";
+        public String name = "subtype1";
+
+        @Override
+        public String getType() {
+            return type;
         }
 
-        // Regardless of composition, each distinct subtype schema must be defined.
-        assertTrue(context.getDefinedModels().containsKey("DuplicateSubTypesChild1"));
-        assertTrue(context.getDefinedModels().containsKey("DuplicateSubTypesChild2"));
+        @Override
+        public String getName() {
+            return name;
+        }
+    }
+
+    static class PolymorphicSubtype2 implements PolymorphicInterface {
+        public String type = "subtype2";
+        public String name = "subtype2";
+
+        @Override
+        public String getType() {
+            return type;
+        }
+
+        @Override
+        public String getName() {
+            return name;
+        }
+    }
+
+    @Test
+    public void optInKeepsSubtypesAllOfParentAndParentProperties() {
+        ModelResolver.jsonSubTypesOneOf = true;
+        final Schema<?> parent = context.resolve(new AnnotatedType(PolymorphicInterface.class));
+        assertTrue(parent instanceof ComposedSchema);
+        assertNotNull(parent.getProperties(), "parent properties must survive the replacement");
+        assertTrue(parent.getProperties().containsKey("name"));
+
+        final Schema<?> sub = context.getDefinedModels().get("PolymorphicSubtype1");
+        assertTrue(sub instanceof ComposedSchema);
+        assertEquals(((ComposedSchema) sub).getAllOf().get(0).get$ref(), "#/components/schemas/PolymorphicInterface");
     }
 
-    @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
+    @Test
+    public void optInOneOfFollowsDeclarationOrderAndUsesResolvedNames() {
+        ModelResolver.jsonSubTypesOneOf = true;
+        final Schema<?> parent = context.resolve(new AnnotatedType(RenamedParent.class));
+        assertNotNull(parent.getOneOf());
+        assertEquals(parent.getOneOf().size(), 2);
+        assertEquals(parent.getOneOf().get(0).get$ref(), "#/components/schemas/RenamedFirst");
+        assertEquals(parent.getOneOf().get(1).get$ref(), "#/components/schemas/RenamedSecond");
+        for (Schema<?> ref : parent.getOneOf()) {
+            final String name = ref.get$ref().substring("#/components/schemas/".length());
+            assertNotNull(context.getDefinedModels().get(name), "dangling $ref in oneOf: " + name);
+        }
+    }
+
+    @Test
+    public void optInExplicitSchemaOneOfWinsOverJsonSubTypes() {
+        ModelResolver.jsonSubTypesOneOf = true;
+        final Schema<?> model = context.resolve(new AnnotatedType(BaseBean.class));
+        assertNotNull(model.getOneOf());
+        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
+    public void optInProducesOneOfRefsForOpenApi31() {
+        ModelResolver.jsonSubTypesOneOf = true;
+        final ModelConverterContextImpl ctx31 =
+                new ModelConverterContextImpl(new ModelResolver(new ObjectMapper()).openapi31(true));
+        final Schema<?> model = ctx31.resolve(new AnnotatedType(PolymorphicInterface.class));
+        assertNotNull(model.getOneOf());
+        assertEquals(model.getOneOf().size(), 2);
+        assertEquals(model.getOneOf().get(0).get$ref(), "#/components/schemas/PolymorphicSubtype1");
+    }
+
+    @Test
+    public void defaultOutputUnchangedForSubtypesParent() {
+        ModelResolver.jsonSubTypesOneOf = false;
+        final Schema<?> parent = context.resolve(new AnnotatedType(PolymorphicInterface.class));
+        assertFalse(parent instanceof ComposedSchema && ((ComposedSchema) parent).getOneOf() != null);
+        assertTrue(parent.getProperties().containsKey("name"));
+        final Schema<?> sub = context.getDefinedModels().get("PolymorphicSubtype1");
+        assertTrue(sub instanceof ComposedSchema);
+        assertEquals(((ComposedSchema) sub).getAllOf().get(0).get$ref(), "#/components/schemas/PolymorphicInterface");
+    }
+
+    @Test
+    public void optInOneOfSkipsSubtypesNotAssignableToParent() {
+        ModelResolver.jsonSubTypesOneOf = true;
+        final Schema<?> parent = context.resolve(new AnnotatedType(ParentWithUnrelatedSubtype.class));
+        assertNotNull(parent.getOneOf());
+        assertEquals(parent.getOneOf().size(), 1);
+        assertEquals(parent.getOneOf().get(0).get$ref(), "#/components/schemas/RelatedImpl");
+    }
+
+    @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "kind")
     @JsonSubTypes({
-            @JsonSubTypes.Type(value = DuplicateSubTypesChild1.class),
-            @JsonSubTypes.Type(value = DuplicateSubTypesChild1.class),
-            @JsonSubTypes.Type(value = DuplicateSubTypesChild2.class)
+            @JsonSubTypes.Type(value = RelatedImpl.class, name = "related"),
+            @JsonSubTypes.Type(value = UnrelatedType.class, name = "unrelated")
     })
-    static abstract class DuplicateSubTypesParent {
-        public String type;
+    static class ParentWithUnrelatedSubtype {
+        public String id;
+    }
+
+    static class RelatedImpl extends ParentWithUnrelatedSubtype {
+        public String x;
+    }
+
+    static class UnrelatedType {
+        public String y;
+    }
+
+    @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "kind")
+    @JsonSubTypes({
+            @JsonSubTypes.Type(value = RenamedFirstImpl.class, name = "first"),
+            @JsonSubTypes.Type(value = RenamedSecondImpl.class, name = "second")
+    })
+    static class RenamedParent {
+        public String id;
     }
 
-    static class DuplicateSubTypesChild1 extends DuplicateSubTypesParent {
+    @io.swagger.v3.oas.annotations.media.Schema(name = "RenamedFirst")
+    static class RenamedFirstImpl extends RenamedParent {
+        public String x;
     }
 
-    static class DuplicateSubTypesChild2 extends DuplicateSubTypesParent {
+    @io.swagger.v3.oas.annotations.media.Schema(name = "RenamedSecond")
+    static class RenamedSecondImpl extends RenamedParent {
+        public String y;
     }
 
     private void assertSubPropertiesValid(Map<String, Schema> subProperties, final String childPropertyName) {