Merge branch 'Mattias-Sehlstedt-use-return-type-schema'

bnasslahsen · bnasslahsen · commit 65de3c10dd9d · 2025-12-25T16:02:49.000+01:00
diff --git a/springdoc-openapi-starter-common/src/main/java/org/springdoc/core/models/MethodAttributes.java b/springdoc-openapi-starter-common/src/main/java/org/springdoc/core/models/MethodAttributes.java
@@ -134,7 +134,7 @@ public class MethodAttributes {
 	/**
 	 * The Use return type schema.
 	 */
-	private boolean useReturnTypeSchema;
+	private final Map<String, Boolean> useReturnTypeSchema = new LinkedHashMap<>();
 
 	/**
 	 * Instantiates a new Method attributes.
@@ -529,20 +529,21 @@ public Locale getLocale() {
 	}
 
 	/**
-	 * Is use return type schema boolean.
+	 * Gets use return type schema.
 	 *
-	 * @return the boolean
+	 * @return the use return type schema
 	 */
-	public boolean isUseReturnTypeSchema() {
+	public Map<String, Boolean> getUseReturnTypeSchema() {
 		return useReturnTypeSchema;
 	}
 
 	/**
-	 * Sets use return type schema.
+	 * Put use return type schema.
 	 *
+	 * @param responseCode the response code
 	 * @param useReturnTypeSchema the use return type schema
 	 */
-	public void setUseReturnTypeSchema(boolean useReturnTypeSchema) {
-		this.useReturnTypeSchema = useReturnTypeSchema;
+	public void putUseReturnTypeSchema(String responseCode, boolean useReturnTypeSchema) {
+        this.useReturnTypeSchema.put(responseCode, useReturnTypeSchema);
 	}
 }
diff --git a/springdoc-openapi-starter-common/src/main/java/org/springdoc/core/service/GenericResponseService.java b/springdoc-openapi-starter-common/src/main/java/org/springdoc/core/service/GenericResponseService.java
@@ -58,10 +58,9 @@
 import io.swagger.v3.oas.models.media.Schema;
 import io.swagger.v3.oas.models.responses.ApiResponse;
 import io.swagger.v3.oas.models.responses.ApiResponses;
+import kotlin.reflect.jvm.internal.impl.load.kotlin.JvmType.Object;
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.StringUtils;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 import org.springdoc.core.models.ControllerAdviceInfo;
 import org.springdoc.core.models.MethodAdviceInfo;
 import org.springdoc.core.models.MethodAttributes;
@@ -97,7 +96,6 @@
 import static org.springdoc.core.utils.SpringDocAnnotationsUtils.extractSchema;
 import static org.springdoc.core.utils.SpringDocAnnotationsUtils.getContent;
 import static org.springdoc.core.utils.SpringDocAnnotationsUtils.mergeSchema;
-import static org.springdoc.core.utils.SpringDocUtils.cloneViaJson;
 import static org.springdoc.core.utils.SpringDocUtils.getParameterAnnotations;
 
 /**
@@ -112,12 +110,7 @@ public class GenericResponseService implements ApplicationContextAware {
 	 * the exception classes.
 	 */
 	private static final String EXTENSION_EXCEPTION_CLASSES = "x-exception-class";
-
-	/**
-	 * The constant LOGGER.
-	 */
-	private static final Logger LOGGER = LoggerFactory.getLogger(GenericResponseService.class);
-
+	
 	/**
 	 * The Response entity exception handler class.
 	 */
@@ -180,22 +173,22 @@ public GenericResponseService(OperationService operationService,
 	 * @param components             the components
 	 * @param apiResponsesOp         the api responses op
 	 * @param methodAttributes       the method attributes
-	 * @param apiResponseAnnotations the api response annotations
+	 * @param apiResponseAnnotation  the api response annotation
 	 * @param apiResponse            the api response
 	 * @param openapi31              the openapi 31
 	 */
 	public static void buildContentFromDoc(Components components, ApiResponses apiResponsesOp,
 			MethodAttributes methodAttributes,
-			io.swagger.v3.oas.annotations.responses.ApiResponse apiResponseAnnotations,
+			io.swagger.v3.oas.annotations.responses.ApiResponse apiResponseAnnotation,
 			ApiResponse apiResponse, boolean openapi31) {
 
-		methodAttributes.setUseReturnTypeSchema(apiResponseAnnotations.useReturnTypeSchema());
-		io.swagger.v3.oas.annotations.media.Content[] contentdoc = apiResponseAnnotations.content();
+		methodAttributes.putUseReturnTypeSchema(apiResponseAnnotation.responseCode(), apiResponseAnnotation.useReturnTypeSchema());
+		io.swagger.v3.oas.annotations.media.Content[] contentdoc = apiResponseAnnotation.content();
 		Optional<Content> optionalContent = getContent(contentdoc, new String[0],
 				methodAttributes.getMethodProduces(), null, components, methodAttributes.getJsonViewAnnotation(), openapi31);
-		if (apiResponsesOp.containsKey(apiResponseAnnotations.responseCode())) {
+		if (apiResponsesOp.containsKey(apiResponseAnnotation.responseCode())) {
 			// Merge with the existing content
-			Content existingContent = apiResponsesOp.get(apiResponseAnnotations.responseCode()).getContent();
+			Content existingContent = apiResponsesOp.get(apiResponseAnnotation.responseCode()).getContent();
 			if (optionalContent.isPresent()) {
 				Content newContent = optionalContent.get();
 				if (methodAttributes.isMethodOverloaded() && existingContent != null) {
@@ -387,17 +380,17 @@ private Map<String, ApiResponse> computeResponseFromDoc(Components components, M
 		Set<io.swagger.v3.oas.annotations.responses.ApiResponse> responsesArray = getApiResponses(Objects.requireNonNull(methodParameter.getMethod()));
 		if (!responsesArray.isEmpty()) {
 			methodAttributes.setWithApiResponseDoc(true);
-			for (io.swagger.v3.oas.annotations.responses.ApiResponse apiResponseAnnotations : responsesArray) {
-				String httpCode = apiResponseAnnotations.responseCode();
+			for (io.swagger.v3.oas.annotations.responses.ApiResponse apiResponseAnnotation : responsesArray) {
+				String httpCode = apiResponseAnnotation.responseCode();
 				ApiResponse apiResponse = new ApiResponse();
-				if (StringUtils.isNotBlank(apiResponseAnnotations.ref())) {
-					apiResponse.$ref(apiResponseAnnotations.ref());
-					apiResponsesOp.addApiResponse(apiResponseAnnotations.responseCode(), apiResponse);
+				if (StringUtils.isNotBlank(apiResponseAnnotation.ref())) {
+					apiResponse.$ref(apiResponseAnnotation.ref());
+					apiResponsesOp.addApiResponse(apiResponseAnnotation.responseCode(), apiResponse);
 					continue;
 				}
-				apiResponse.setDescription(propertyResolverUtils.resolve(apiResponseAnnotations.description(), methodAttributes.getLocale()));
-				buildContentFromDoc(components, apiResponsesOp, methodAttributes, apiResponseAnnotations, apiResponse, openapi31);
-				Map<String, Object> extensions = AnnotationsUtils.getExtensions(propertyResolverUtils.isOpenapi31(), apiResponseAnnotations.extensions());
+				apiResponse.setDescription(propertyResolverUtils.resolve(apiResponseAnnotation.description(), methodAttributes.getLocale()));
+				buildContentFromDoc(components, apiResponsesOp, methodAttributes, apiResponseAnnotation, apiResponse, openapi31);
+				Map<String, Object> extensions = AnnotationsUtils.getExtensions(propertyResolverUtils.isOpenapi31(), apiResponseAnnotation.extensions());
 				if (!CollectionUtils.isEmpty(extensions)) {
 					if (propertyResolverUtils.isResolveExtensionsProperties()) {
 						Map<String, Object> extensionsResolved = propertyResolverUtils.resolveExtensions(locale, extensions);
@@ -407,7 +400,7 @@ private Map<String, ApiResponse> computeResponseFromDoc(Components components, M
 						apiResponse.extensions(extensions);
 					}
 				}
-				SpringDocAnnotationsUtils.getHeaders(apiResponseAnnotations.headers(), components, methodAttributes.getJsonViewAnnotation(), openapi31)
+				SpringDocAnnotationsUtils.getHeaders(apiResponseAnnotation.headers(), components, methodAttributes.getJsonViewAnnotation(), openapi31)
 						.ifPresent(apiResponse::headers);
 				apiResponsesOp.addApiResponse(httpCode, apiResponse);
 			}
@@ -622,8 +615,7 @@ else if (CollectionUtils.isEmpty(apiResponse.getContent()))
 					setDescription(httpCode, apiResponse);
 			}
 		}
-		if (apiResponse.getContent() != null && (methodAttributes.isUseReturnTypeSchema() ||
-				((isGeneric || methodAttributes.isMethodOverloaded()) && methodAttributes.isNoApiResponseDoc()))) {
+		if (apiResponse.getContent() != null && shouldCalculateContent(methodAttributes, isGeneric, httpCode)) {
 			// Merge with existing schema
 			Content existingContent = apiResponse.getContent();
 			Type type = GenericTypeResolver.resolveType(methodParameter.getGenericParameterType(), methodParameter.getContainingClass());
@@ -642,6 +634,28 @@ else if (CollectionUtils.isEmpty(apiResponse.getContent()))
 		apiResponsesOp.addApiResponse(httpCode, apiResponse);
 	}
 
+	/**
+	 * Whether to consider calculating additional content.
+	 *
+	 * @param methodAttributes the method attributes
+	 * @param isGeneric        the is generic
+	 * @param httpCode         the http code
+	 */
+	private boolean shouldCalculateContent(MethodAttributes methodAttributes, boolean isGeneric, String httpCode) {
+		return useReturnTypeSchema(methodAttributes, httpCode) ||
+			   ((isGeneric || methodAttributes.isMethodOverloaded()) && methodAttributes.isNoApiResponseDoc());
+	}
+
+	/**
+	 * Whether to use return type schema.
+	 *
+	 * @param methodAttributes the method attributes
+	 * @param httpCode         the http code
+	 */
+	private boolean useReturnTypeSchema(MethodAttributes methodAttributes, String httpCode) {
+		return methodAttributes.getUseReturnTypeSchema().getOrDefault(httpCode, false);
+	}
+
 	/**
 	 * Evaluate response status string.
 	 *
diff --git a/springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app226/HelloController.java b/springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app226/HelloController.java
@@ -4,8 +4,10 @@
 
 import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.media.ExampleObject;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -17,20 +19,35 @@
 @RequestMapping
 public class HelloController {
 
+	public record Error(String message) {
+
+	}
+
 	@PostMapping("/testBoolean")
-	@ApiResponse(
-			useReturnTypeSchema = true,
-			responseCode = "200",
-			description = "OK",
-			content = {
-					@Content(
-							mediaType = "*/*",
-							examples =
-							@ExampleObject(
-									name = "success",
-									value = "..."))
-			}
-	)
+	@ApiResponses(value = {
+			@ApiResponse(
+					useReturnTypeSchema = true,
+					responseCode = "200",
+					description = "OK",
+					content = {
+							@Content(
+									mediaType = "*/*",
+									examples =
+									@ExampleObject(
+											name = "success",
+											value = "..."))
+					}
+			),
+			@ApiResponse(
+					responseCode = "400",
+					description = "OK",
+					content = {
+							@Content(
+									mediaType = "*/*",
+									schema = @Schema(implementation = Error.class))
+					}
+			)
+	})
 	public Map<String, String> HelloController() {
 		return null;
 	}
diff --git a/springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app226/HelloController.java b/springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app226/HelloController.java
@@ -4,8 +4,10 @@
 
 import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.media.ExampleObject;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -17,20 +19,35 @@
 @RequestMapping
 public class HelloController {
 
+	public record Error(String message) {
+
+	}
+
 	@PostMapping("/testBoolean")
-	@ApiResponse(
-			useReturnTypeSchema = true,
-			responseCode = "200",
-			description = "OK",
-			content = {
-					@Content(
-							mediaType = "*/*",
-							examples =
-							@ExampleObject(
-									name = "success",
-									value = "..."))
-			}
-	)
+	@ApiResponses(value = {
+			@ApiResponse(
+					useReturnTypeSchema = true,
+					responseCode = "200",
+					description = "OK",
+					content = {
+							@Content(
+									mediaType = "*/*",
+									examples =
+									@ExampleObject(
+											name = "success",
+											value = "..."))
+					}
+			),
+			@ApiResponse(
+					responseCode = "400",
+					description = "OK",
+					content = {
+							@Content(
+									mediaType = "*/*",
+									schema = @Schema(implementation = Error.class))
+					}
+			)
+	})
 	public Map<String, String> HelloController() {
 		return null;
 	}
diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app226.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app226.json
@@ -36,10 +36,31 @@
                 }
               }
             }
+          },
+          "400" : {
+            "description" : "OK",
+            "content" : {
+              "*/*" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/Error"
+                }
+              }
+            }
           }
         }
       }
     }
   },
-  "components": {}
+  "components": {
+    "schemas" : {
+      "Error" : {
+        "type" : "object",
+        "properties" : {
+          "message" : {
+            "type" : "string"
+          }
+        }
+      }
+    }
+  }
 }
diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app226.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app226.json

Original file line number	Diff line number	Diff line change
`@@ -134,7 +134,7 @@ public class MethodAttributes {`
`134`	`134`	`/**`
`135`	`135`	`* The Use return type schema.`
`136`	`136`	`*/`
`137`		`- private boolean useReturnTypeSchema;`
	`137`	`+ private final Map<String, Boolean> useReturnTypeSchema = new LinkedHashMap<>();`
`138`	`138`
`139`	`139`	`/**`
`140`	`140`	`* Instantiates a new Method attributes.`
`@@ -529,20 +529,21 @@ public Locale getLocale() {`
`529`	`529`	`}`
`530`	`530`
`531`	`531`	`/**`
`532`		`- * Is use return type schema boolean.`
	`532`	`+ * Gets use return type schema.`
`533`	`533`	`*`
`534`		`- * @return the boolean`
	`534`	`+ * @return the use return type schema`
`535`	`535`	`*/`
`536`		`- public boolean isUseReturnTypeSchema() {`
	`536`	`+ public Map<String, Boolean> getUseReturnTypeSchema() {`
`537`	`537`	`return useReturnTypeSchema;`
`538`	`538`	`}`
`539`	`539`
`540`	`540`	`/**`
`541`		`- * Sets use return type schema.`
	`541`	`+ * Put use return type schema.`
`542`	`542`	`*`
	`543`	`+ * @param responseCode the response code`
`543`	`544`	`* @param useReturnTypeSchema the use return type schema`
`544`	`545`	`*/`
`545`		`- public void setUseReturnTypeSchema(boolean useReturnTypeSchema) {`
`546`		`- this.useReturnTypeSchema = useReturnTypeSchema;`
	`546`	`+ public void putUseReturnTypeSchema(String responseCode, boolean useReturnTypeSchema) {`
	`547`	`+ this.useReturnTypeSchema.put(responseCode, useReturnTypeSchema);`
`547`	`548`	`}`
`548`	`549`	`}`
Original file line number	Diff line number	Diff line change
`@@ -36,10 +36,31 @@`
`36`	`36`	`}`
`37`	`37`	`}`
`38`	`38`	`}`
	`39`	`+ },`
	`40`	`+ "400" : {`
	`41`	`+ "description" : "OK",`
	`42`	`+ "content" : {`
	`43`	`+ "/" : {`
	`44`	`+ "schema" : {`
	`45`	`+ "$ref" : "#/components/schemas/Error"`
	`46`	`+ }`
	`47`	`+ }`
	`48`	`+ }`
`39`	`49`	`}`
`40`	`50`	`}`
`41`	`51`	`}`
`42`	`52`	`}`
`43`	`53`	`},`
`44`		`- "components": {}`
	`54`	`+ "components": {`
	`55`	`+ "schemas" : {`
	`56`	`+ "Error" : {`
	`57`	`+ "type" : "object",`
	`58`	`+ "properties" : {`
	`59`	`+ "message" : {`
	`60`	`+ "type" : "string"`
	`61`	`+ }`
	`62`	`+ }`
	`63`	`+ }`
	`64`	`+ }`
	`65`	`+ }`
`45`	`66`	`}`