Content definition in @ApiResponse remove schema generated based on the returned value. Fixes #2663

Author: bnasslahsen

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/models/MethodAttributes.java

@@ -128,6 +128,11 @@ public class MethodAttributes {
 	 */
 	private String javadocReturn;
 
+	/**
+	 * The Use return type schema.
+	 */
+	private boolean useReturnTypeSchema;
+	
 	/**
 	 * Instantiates a new Method attributes.
 	 * @param methodProducesNew the method produces new
@@ -493,4 +498,22 @@ public void setJavadocReturn(String javadocReturn) {
 	public Locale getLocale() {
 		return locale;
 	}
+
+	/**
+	 * Is use return type schema boolean.
+	 *
+	 * @return the boolean
+	 */
+	public boolean isUseReturnTypeSchema() {
+		return useReturnTypeSchema;
+	}
+
+	/**
+	 * Sets use return type schema.
+	 *
+	 * @param useReturnTypeSchema the use return type schema
+	 */
+	public void setUseReturnTypeSchema(boolean useReturnTypeSchema) {
+		this.useReturnTypeSchema = useReturnTypeSchema;
+	}
 }

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/service/GenericResponseService.java

@@ -181,6 +181,7 @@ public static void buildContentFromDoc(Components components, ApiResponses apiRe
 			io.swagger.v3.oas.annotations.responses.ApiResponse apiResponseAnnotations,
 			ApiResponse apiResponse, boolean openapi31) {
 
+		methodAttributes.setUseReturnTypeSchema(apiResponseAnnotations.useReturnTypeSchema());
 		io.swagger.v3.oas.annotations.media.Content[] contentdoc = apiResponseAnnotations.content();
 		Optional<Content> optionalContent = getContent(contentdoc, new String[0],
 				methodAttributes.getMethodProduces(), null, components, methodAttributes.getJsonViewAnnotation(), openapi31);
@@ -620,8 +621,8 @@ else if (CollectionUtils.isEmpty(apiResponse.getContent()))
 					setDescription(httpCode, apiResponse);
 			}
 		}
-		if (apiResponse.getContent() != null
-				&& ((isGeneric || methodAttributes.isMethodOverloaded()) && methodAttributes.isNoApiResponseDoc())) {
+		if (apiResponse.getContent() != null && (methodAttributes.isUseReturnTypeSchema() ||
+			 ((isGeneric || methodAttributes.isMethodOverloaded()) && methodAttributes.isNoApiResponseDoc()))) {
 			// Merge with existing schema
 			Content existingContent = apiResponse.getContent();
 			Type type = ReturnTypeParser.getType(methodParameter);

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/utils/SpringDocAnnotationsUtils.java

@@ -34,6 +34,7 @@
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Map.Entry;
 import java.util.Optional;
 import java.util.Set;
 
@@ -45,6 +46,7 @@
 import io.swagger.v3.core.converter.ResolvedSchema;
 import io.swagger.v3.core.util.AnnotationsUtils;
 import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.media.Encoding;
 import io.swagger.v3.oas.annotations.media.ExampleObject;
 import io.swagger.v3.oas.annotations.media.SchemaProperty;
 import io.swagger.v3.oas.models.Components;
@@ -142,7 +144,7 @@ public static Schema extractSchema(Components components, Type returnType, JsonV
 					componentSchemas.putAll(schemaMap);
 				}
 				else
-					for (Map.Entry<String, Schema> entry : schemaMap.entrySet()) {
+					for (Entry<String, Schema> entry : schemaMap.entrySet()) {
 						// If we've seen this schema before but find later it should be polymorphic,
 						// replace the existing schema with this richer version.
 						Schema existingSchema = componentSchemas.get(entry.getKey());
@@ -200,7 +202,7 @@ public static Optional<Content> getContent(io.swagger.v3.oas.annotations.media.C
 			ExampleObject[] examples = annotationContent.examples();
 			setExamples(mediaType, examples);
 			addExtension(annotationContent, mediaType, openapi31);
-			io.swagger.v3.oas.annotations.media.Encoding[] encodings = annotationContent.encoding();
+			Encoding[] encodings = annotationContent.encoding();
 			addEncodingToMediaType(jsonViewAnnotation, mediaType, encodings, openapi31);
 			if (StringUtils.isNotBlank(annotationContent.mediaType())) {
 				content.addMediaType(annotationContent.mediaType(), mediaType);
@@ -230,8 +232,11 @@ public static void mergeSchema(Content existingContent, Schema<?> schemaN, Strin
 			if (!schemaN.equals(mediaType.getSchema())) {
 				// Merge the two schemas for the same mediaType
 				Schema firstSchema = mediaType.getSchema();
-				ComposedSchema schemaObject;
-				if (firstSchema instanceof ComposedSchema) {
+				Schema<?> schemaObject = null;
+				if (firstSchema == null) {
+					schemaObject = schemaN;
+				}
+				else if (firstSchema instanceof ComposedSchema) {
 					schemaObject = (ComposedSchema) firstSchema;
 					List<Schema> listOneOf = schemaObject.getOneOf();
 					if (!CollectionUtils.isEmpty(listOneOf) && !listOneOf.contains(schemaN))
@@ -311,8 +316,8 @@ public static void removeAnnotationsToIgnore(Class<?>... classes) {
 	 * @param openapi31          the openapi 31
 	 */
 	private static void addEncodingToMediaType(JsonView jsonViewAnnotation, MediaType mediaType,
-			io.swagger.v3.oas.annotations.media.Encoding[] encodings, boolean openapi31) {
-		for (io.swagger.v3.oas.annotations.media.Encoding encoding : encodings) {
+			Encoding[] encodings, boolean openapi31) {
+		for (Encoding encoding : encodings) {
 			addEncodingToMediaType(mediaType, encoding, jsonViewAnnotation, openapi31);
 		}
 	}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app226/HelloController.java

@@ -0,0 +1,37 @@
+package test.org.springdoc.api.v30.app226;
+
+import java.util.Map;
+
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * @author bnasslahsen
+ */
+@RestController
+@RequestMapping
+public class HelloController {
+
+	@PostMapping("/testBoolean")
+	@ApiResponse(
+			useReturnTypeSchema = true,
+			responseCode = "200",
+			description = "OK",
+			content = {
+					@Content(
+							mediaType = "*/*",
+							examples =
+							@ExampleObject(
+									name = "success",
+									value ="..."))
+			}
+	)
+	public Map<String, String> HelloController() {
+		return null;
+	}
+}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app226/SpringDocApp226Test.java

@@ -0,0 +1,35 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * Copyright 2019-2022 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 test.org.springdoc.api.v30.app226;
+
+import test.org.springdoc.api.v30.AbstractSpringDocV30Test;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+public class SpringDocApp226Test extends AbstractSpringDocV30Test {
+
+	@SpringBootApplication
+	static class SpringDocTestApp {}
+}

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app226.json

@@ -0,0 +1,45 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "OpenAPI definition",
+    "version": "v0"
+  },
+  "servers": [
+    {
+      "url": "http://localhost",
+      "description": "Generated server url"
+    }
+  ],
+  "paths": {
+    "/testBoolean": {
+      "post": {
+        "tags": [
+          "hello-controller"
+        ],
+        "operationId": "HelloController",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                "examples": {
+                  "success": {
+                    "description": "success",
+                    "value": "..."
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {}
+}