Changes report: Change so useReturnTypeSchema is considered on an http code level #3141

bnasslahsen · bnasslahsen · commit e0bc5b9671e8 · 2025-12-25T16:03:29.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
@@ -137,7 +137,7 @@ public class MethodAttributes {
 	/**
 	 * The Use return type schema.
 	 */
-	private boolean useReturnTypeSchema;
+	private final Map<String, Boolean> useReturnTypeSchema = new LinkedHashMap<>();
 
 	/**
 	 * The Spring doc version strategy.
@@ -585,21 +585,22 @@ 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
@@ -60,8 +60,6 @@
 import io.swagger.v3.oas.models.responses.ApiResponses;
 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;
@@ -113,11 +111,6 @@ public class GenericResponseService implements ApplicationContextAware {
 	 */
 	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 annotations
 	 * @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) {
@@ -217,6 +210,7 @@ public static void buildContentFromDoc(Components components, ApiResponses apiRe
 		}
 	}
 
+
 	/**
 	 * Sets description.
 	 *
@@ -387,17 +381,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 +401,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 +616,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 +635,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
`@@ -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`	`}`