Provide better compatibility for projects migrating from OAS 3.0 to OAS 3.1. Fixes #2849

Author: bnasslahsen

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/configuration/SpringDocConfiguration.java

@@ -21,7 +21,7 @@
  *  *  *  *
  *  *  *
  *  *
- *  
+ *
  */
 
 
@@ -52,6 +52,7 @@
 import org.springdoc.core.converters.AdditionalModelsConverter;
 import org.springdoc.core.converters.FileSupportConverter;
 import org.springdoc.core.converters.ModelConverterRegistrar;
+import org.springdoc.core.converters.OAS31ModelConverter;
 import org.springdoc.core.converters.PolymorphicModelConverter;
 import org.springdoc.core.converters.PropertyCustomizingConverter;
 import org.springdoc.core.converters.ResponseSupportConverter;
@@ -597,14 +598,14 @@ public SpringDocCustomizers springDocCustomizers(Optional<Set<OpenApiCustomizer>
 			Optional<Set<OperationCustomizer>> operationCustomizers,
 			Optional<Set<RouterOperationCustomizer>> routerOperationCustomizers,
 			Optional<Set<DataRestRouterOperationCustomizer>> dataRestRouterOperationCustomizers,
-			Optional<Set<OpenApiMethodFilter>> methodFilters, Optional<Set<GlobalOpenApiCustomizer>> globalOpenApiCustomizers, 
+			Optional<Set<OpenApiMethodFilter>> methodFilters, Optional<Set<GlobalOpenApiCustomizer>> globalOpenApiCustomizers,
 			Optional<Set<GlobalOperationCustomizer>> globalOperationCustomizers,
-			Optional<Set<GlobalOpenApiMethodFilter>> globalOpenApiMethodFilters){
+			Optional<Set<GlobalOpenApiMethodFilter>> globalOpenApiMethodFilters) {
 		return new SpringDocCustomizers(openApiCustomizers,
 				operationCustomizers,
-				 routerOperationCustomizers,
-				 dataRestRouterOperationCustomizers,
-				 methodFilters, globalOpenApiCustomizers, globalOperationCustomizers, globalOpenApiMethodFilters);
+				routerOperationCustomizers,
+				dataRestRouterOperationCustomizers,
+				methodFilters, globalOpenApiCustomizers, globalOperationCustomizers, globalOpenApiMethodFilters);
 	}
 
 	/**
@@ -658,4 +659,17 @@ ParameterObjectNamingStrategyCustomizer parameterObjectNamingStrategyCustomizer(
 	GlobalOpenApiCustomizer globalOpenApiCustomizer() {
 		return new OperationIdCustomizer();
 	}
+
+	/**
+	 * Oas 31 model converter oas 31 model converter.
+	 *
+	 * @param springDocConfigProperties the spring doc config properties
+	 * @return the oas 31 model converter
+	 */
+	@Bean
+	@ConditionalOnMissingBean
+	@Lazy(false)
+	OAS31ModelConverter oas31ModelConverter(SpringDocConfigProperties springDocConfigProperties) {
+		return springDocConfigProperties.isOpenapi31() ? new OAS31ModelConverter() : null;
+	}
 }

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/configuration/SpringDocHateoasConfiguration.java

@@ -31,7 +31,7 @@
 import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.databind.SerializerProvider;
 import org.springdoc.core.converters.CollectionModelContentConverter;
-import org.springdoc.core.converters.RepresentationModelLinksOASMixin;
+import org.springdoc.core.converters.HateoasLinksConverter;
 import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
 import org.springdoc.core.customizers.OpenApiHateoasLinksCustomizer;
 import org.springdoc.core.properties.SpringDocConfigProperties;
@@ -49,7 +49,6 @@
 import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Lazy;
 import org.springframework.hateoas.Links;
-import org.springframework.hateoas.RepresentationModel;
 import org.springframework.hateoas.server.LinkRelationProvider;
 
 /**
@@ -99,20 +98,32 @@ CollectionModelContentConverter collectionModelContentConverter(HateoasHalProvid
 	 *
 	 * @param halProvider               the hal provider
 	 * @param springDocConfigProperties the spring doc config properties
-	 * @param objectMapperProvider      the object mapper provider
 	 * @return the open api customizer
-	 * @see org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider) org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)
+	 * @see org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider) org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)org.springframework.hateoas.mediatype.hal.Jackson2HalModule.HalLinkListSerializer#serialize(Links, JsonGenerator, SerializerProvider)
 	 */
 	@Bean(Constants.LINKS_SCHEMA_CUSTOMISER)
 	@ConditionalOnMissingBean(name = Constants.LINKS_SCHEMA_CUSTOMISER)
 	@Lazy(false)
-	GlobalOpenApiCustomizer linksSchemaCustomizer(HateoasHalProvider halProvider, SpringDocConfigProperties springDocConfigProperties,
-			ObjectMapperProvider objectMapperProvider) {
+	GlobalOpenApiCustomizer linksSchemaCustomizer(HateoasHalProvider halProvider, SpringDocConfigProperties springDocConfigProperties) {
 		if (!halProvider.isHalEnabled()) {
 			return openApi -> {
 			};
 		}
-		objectMapperProvider.jsonMapper().addMixIn(RepresentationModel.class, RepresentationModelLinksOASMixin.class);
 		return new OpenApiHateoasLinksCustomizer(springDocConfigProperties);
 	}
+
+	/**
+	 * Hateoas links converter hateoas links converter.
+	 *
+	 * @param springDocObjectMapper the spring doc object mapper
+	 * @return the hateoas links converter
+	 */
+	@Bean
+	@ConditionalOnMissingBean
+	@Lazy(false)
+	HateoasLinksConverter hateoasLinksConverter(ObjectMapperProvider springDocObjectMapper) {
+		return new HateoasLinksConverter(springDocObjectMapper) ;
+	}
+	
+	
 }

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/converters/AdditionalModelsConverter.java

@@ -41,6 +41,8 @@
 import org.slf4j.LoggerFactory;
 import org.springdoc.core.providers.ObjectMapperProvider;
 
+import static org.springdoc.core.utils.SpringDocUtils.handleSchemaTypes;
+
 /**
  * The type Additional models converter.
  *
@@ -146,8 +148,11 @@ public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterato
 			Class<?> cls = javaType.getRawClass();
 			if (modelToSchemaMap.containsKey(cls))
 				try {
+					Schema schema = modelToSchemaMap.get(cls);
+					if(springDocObjectMapper.isOpenapi31())
+						handleSchemaTypes(schema);
 					return springDocObjectMapper.jsonMapper()
-							.readValue(springDocObjectMapper.jsonMapper().writeValueAsString(modelToSchemaMap.get(cls)), new TypeReference<Schema>() {});
+							.readValue(springDocObjectMapper.jsonMapper().writeValueAsString(schema), new TypeReference<Schema>() {});
 				}
 				catch (JsonProcessingException e) {
 					LOGGER.warn("Json Processing Exception occurred: {}", e.getMessage());

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/converters/HateoasLinksConverter.java

@@ -0,0 +1,92 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * Copyright 2019-2025 the original author or authors.
+ *  *  *  *  *  *
+ *  *  *  *  *  * Licensed under the Apache License, Version 2.0 (the "License");
+ *  *  *  *  *  * you may not use this file except in compliance with the License.
+ *  *  *  *  *  * You may obtain a copy of the License at
+ *  *  *  *  *  *
+ *  *  *  *  *  *      https://www.apache.org/licenses/LICENSE-2.0
+ *  *  *  *  *  *
+ *  *  *  *  *  * Unless required by applicable law or agreed to in writing, software
+ *  *  *  *  *  * distributed under the License is distributed on an "AS IS" BASIS,
+ *  *  *  *  *  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  *  *  *  *  * See the License for the specific language governing permissions and
+ *  *  *  *  *  * limitations under the License.
+ *  *  *  *  *
+ *  *  *  *
+ *  *  *
+ *  *
+ *
+ */
+
+package org.springdoc.core.converters;
+
+
+import java.util.Iterator;
+
+import com.fasterxml.jackson.databind.JavaType;
+import io.swagger.v3.core.converter.ModelConverter;
+import io.swagger.v3.core.converter.ModelConverterContext;
+import io.swagger.v3.core.util.AnnotationsUtils;
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.media.ArraySchema;
+import io.swagger.v3.oas.models.media.JsonSchema;
+import io.swagger.v3.oas.models.media.Schema;
+import org.springdoc.core.providers.ObjectMapperProvider;
+
+import org.springframework.hateoas.RepresentationModel;
+
+/**
+ * The type Hateoas links converter.
+ * 
+ * @author bnasslahsen
+ */
+public class HateoasLinksConverter implements ModelConverter {
+
+	/**
+	 * The Spring doc object mapper.
+	 */
+	private final ObjectMapperProvider springDocObjectMapper;
+
+	/**
+	 * Instantiates a new Hateoas links converter.
+	 *
+	 * @param springDocObjectMapper the spring doc object mapper
+	 */
+	public HateoasLinksConverter(ObjectMapperProvider springDocObjectMapper) {
+		this.springDocObjectMapper = springDocObjectMapper;
+	}
+
+	@Override
+	public Schema<?> resolve(
+			io.swagger.v3.core.converter.AnnotatedType type,
+			ModelConverterContext context,
+			Iterator<ModelConverter> chain
+	) {
+		JavaType javaType = springDocObjectMapper.jsonMapper().constructType(type.getType());
+		if (javaType != null) {
+			if (RepresentationModel.class.isAssignableFrom(javaType.getRawClass())) {
+				Schema<?> schema = chain.next().resolve(type, context, chain);
+				String schemaName = schema.get$ref().substring(Components.COMPONENTS_SCHEMAS_REF.length());
+				Schema original = context.getDefinedModels().get(schemaName);
+				Object links = original.getProperties().get("_links");
+				if(links instanceof JsonSchema jsonSchema) {
+					jsonSchema.set$ref(AnnotationsUtils.COMPONENTS_REF + "Links");
+					jsonSchema.setType(null);
+					jsonSchema.setItems(null);
+					jsonSchema.setTypes(null);
+				} else if (links instanceof ArraySchema arraySchema){
+					arraySchema.set$ref(AnnotationsUtils.COMPONENTS_REF + "Links");
+				}
+				return schema;
+			}
+		}
+		return chain.hasNext() ? chain.next().resolve(type, context, chain) : null;
+	}
+
+}

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/converters/OAS31ModelConverter.java

@@ -0,0 +1,58 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * Copyright 2019-2025 the original author or authors.
+ *  *  *  *  *  *
+ *  *  *  *  *  * Licensed under the Apache License, Version 2.0 (the "License");
+ *  *  *  *  *  * you may not use this file except in compliance with the License.
+ *  *  *  *  *  * You may obtain a copy of the License at
+ *  *  *  *  *  *
+ *  *  *  *  *  *      https://www.apache.org/licenses/LICENSE-2.0
+ *  *  *  *  *  *
+ *  *  *  *  *  * Unless required by applicable law or agreed to in writing, software
+ *  *  *  *  *  * distributed under the License is distributed on an "AS IS" BASIS,
+ *  *  *  *  *  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  *  *  *  *  * See the License for the specific language governing permissions and
+ *  *  *  *  *  * limitations under the License.
+ *  *  *  *  *
+ *  *  *  *
+ *  *  *
+ *  *
+ *
+ */
+
+package org.springdoc.core.converters;
+
+import java.util.Iterator;
+
+import io.swagger.v3.core.converter.AnnotatedType;
+import io.swagger.v3.core.converter.ModelConverter;
+import io.swagger.v3.core.converter.ModelConverterContext;
+import io.swagger.v3.oas.models.media.Schema;
+
+import static org.springdoc.core.utils.SpringDocUtils.handleSchemaTypes;
+import static org.springdoc.core.utils.SpringDocUtils.isComposedSchema;
+
+/**
+ * The type OAS31 Model converter.
+ *
+ * @author bnasslahsen
+ */
+public class OAS31ModelConverter implements ModelConverter {
+
+	@Override
+	public Schema<?> resolve(AnnotatedType type, ModelConverterContext context, Iterator<ModelConverter> chain) {
+		if (chain.hasNext()) {
+			Schema<?> resolvedSchema = chain.next().resolve(type, context, chain);
+			if (resolvedSchema != null && !isComposedSchema(resolvedSchema)) {
+				handleSchemaTypes(resolvedSchema);
+			}
+			return resolvedSchema;
+		}
+		return null;
+	}
+
+}

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/converters/PageOpenAPIConverter.java

@@ -35,12 +35,13 @@
 import io.swagger.v3.core.converter.ModelConverter;
 import io.swagger.v3.core.converter.ModelConverterContext;
 import io.swagger.v3.oas.models.media.Schema;
-import org.apache.commons.lang3.StringUtils;
 import org.springdoc.core.providers.ObjectMapperProvider;
 
 import org.springframework.core.ResolvableType;
 import org.springframework.data.web.PagedModel;
 
+import static org.springdoc.core.utils.SpringDocUtils.getParentTypeName;
+
 /**
  * The Spring Data Page type model converter.
  *
@@ -95,7 +96,7 @@ public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterato
 				if (!type.isSchemaProperty())
 					type = resolvePagedModelType(type);
 				else
-					type.name(cls.getSimpleName() + StringUtils.capitalize(type.getParent().getType()));
+					type.name(getParentTypeName(type, cls));
 			}
 		}
 		return (chain.hasNext()) ? chain.next().resolve(type, context, chain) : null;

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/converters/PageableOpenAPIConverter.java

@@ -33,10 +33,11 @@
 import io.swagger.v3.core.converter.ModelConverter;
 import io.swagger.v3.core.converter.ModelConverterContext;
 import io.swagger.v3.oas.models.media.Schema;
-import org.apache.commons.lang3.StringUtils;
 import org.springdoc.core.converters.models.Pageable;
 import org.springdoc.core.providers.ObjectMapperProvider;
 
+import static org.springdoc.core.utils.SpringDocUtils.getParentTypeName;
+
 /**
  * The Pageable Type models converter.
  *
@@ -90,7 +91,7 @@ public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterato
 				if (!type.isSchemaProperty())
 					type = PAGEABLE;
 				else
-					type.name(cls.getSimpleName() + StringUtils.capitalize(type.getParent().getType()));
+					type.name(getParentTypeName(type, cls));
 			}
 		}
 		return (chain.hasNext()) ? chain.next().resolve(type, context, chain) : null;

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/converters/PolymorphicModelConverter.java

@@ -21,7 +21,7 @@
  *  *  *  *
  *  *  *
  *  *
- *  
+ *
  */
 
 package org.springdoc.core.converters;
@@ -64,6 +64,11 @@ public class PolymorphicModelConverter implements ModelConverter {
 	 */
 	private static final List<String> PARENT_TYPES_TO_IGNORE = Collections.synchronizedList(new ArrayList<>());
 
+	/**
+	 * The constant PARENT_TYPES_TO_IGNORE.
+	 */
+	private static final List<String> TYPES_TO_SKIP = Collections.synchronizedList(new ArrayList<>());
+	
 	static {
 		PARENT_TYPES_TO_IGNORE.add("JsonSchema");
 		PARENT_TYPES_TO_IGNORE.add("Pageable");
@@ -115,6 +120,9 @@ public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterato
 				if (field.isAnnotationPresent(JsonUnwrapped.class)) {
 					PARENT_TYPES_TO_IGNORE.add(javaType.getRawClass().getSimpleName());
 				}
+				else if (field.isAnnotationPresent(io.swagger.v3.oas.annotations.media.Schema.class)) {
+					TYPES_TO_SKIP.add(field.getType().getSimpleName());
+				}
 			}
 			if (chain.hasNext()) {
 				if (!type.isResolveAsRef() && type.getParent() != null
@@ -149,12 +157,13 @@ public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterato
 	private Schema composePolymorphicSchema(AnnotatedType type, Schema schema, Collection<Schema> schemas) {
 		String ref = schema.get$ref();
 		List<Schema> composedSchemas = findComposedSchemas(ref, schemas);
-
 		if (composedSchemas.isEmpty()) return schema;
-
 		ComposedSchema result = new ComposedSchema();
 		if (isConcreteClass(type)) result.addOneOfItem(schema);
-		composedSchemas.forEach(result::addOneOfItem);
+		JavaType javaType = springDocObjectMapper.jsonMapper().constructType(type.getType());
+		Class<?> clazz = javaType.getRawClass();
+		if(TYPES_TO_SKIP.stream().noneMatch(typeToSkip -> typeToSkip.equals(clazz.getSimpleName())))
+			composedSchemas.forEach(result::addOneOfItem);
 		return result;
 	}