Merge pull request #2371 from westse/no-empty-desc

No empty description for polymorphic subtypes

Author: bnasslahsen

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/JavadocPropertyCustomizer.java

@@ -102,7 +102,10 @@ else if (resolvedSchema != null && resolvedSchema.get$ref() != null && resolvedS
 	private void setJavadocDescription(Class<?> cls, List<Field> fields, Schema existingSchema) {
 		if (existingSchema != null) {
 			if (StringUtils.isBlank(existingSchema.getDescription())) {
-				existingSchema.setDescription(javadocProvider.getClassJavadoc(cls));
+				String classJavadoc = javadocProvider.getClassJavadoc(cls);
+				if (StringUtils.isNotBlank(classJavadoc)) {
+					existingSchema.setDescription(classJavadoc);
+				}
 			}
 			Map<String, Schema> properties = existingSchema.getProperties();
 			if (!CollectionUtils.isEmpty(properties)) {

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/app170/Animal.java

@@ -0,0 +1,17 @@
+package test.org.springdoc.api.app170;
+
+
+import com.fasterxml.jackson.annotation.JsonSubTypes;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+/**
+ * Interface of the Animal.
+ */
+@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.WRAPPER_OBJECT)
+@JsonSubTypes({
+		@JsonSubTypes.Type(value = Dog.class, name = "dog"),
+		@JsonSubTypes.Type(value = Cat.class, name = "cat"),
+})
+@Schema(description = "Represents an Animal class.")
+public interface Animal {}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/app170/BasicController.java

@@ -0,0 +1,19 @@
+package test.org.springdoc.api.app170;
+
+import io.swagger.v3.oas.annotations.Operation;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping(path = "/")
+public class BasicController {
+
+	@GetMapping("/test1")
+	@Operation(summary = "get1", description = "Provides an animal.")
+	public Animal get1() {
+
+		return new Dog("Foo", 12);
+	}
+}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/app170/Cat.java

@@ -0,0 +1,22 @@
+package test.org.springdoc.api.app170;
+
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema
+public class Cat implements Animal {
+
+	private Integer speed;
+
+	public Cat(Integer speed) {
+		this.speed = speed;
+	}
+
+	public Integer getSpeed() {
+		return speed;
+	}
+
+	public void setSpeed(Integer speed) {
+		this.speed = speed;
+	}
+}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/app170/Dog.java

@@ -0,0 +1,33 @@
+package test.org.springdoc.api.app170;
+
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "Represents a Dog class.")
+public class Dog implements Animal {
+
+	private String name;
+
+	private Integer age;
+
+	public Dog(String name, Integer age) {
+		this.name = name;
+		this.age = age;
+	}
+
+	public String getName() {
+		return name;
+	}
+
+	public void setName(String name) {
+		this.name = name;
+	}
+
+	public Integer getAge() {
+		return age;
+	}
+
+	public void setAge(Integer age) {
+		this.age = age;
+	}
+}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/app170/SpringDocApp170Test.java

@@ -0,0 +1,37 @@
+/*
+ *
+ *  * Copyright 2019-2023 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.app170;
+
+import test.org.springdoc.api.AbstractSpringDocTest;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * The type Spring doc app 193 test.
+ */
+public class SpringDocApp170Test extends AbstractSpringDocTest {
+
+	/**
+	 * The type Spring doc test app.
+	 */
+	@SpringBootApplication
+	static class SpringDocTestApp {
+	}
+
+}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/resources/results/app170.json

@@ -0,0 +1,90 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "OpenAPI definition",
+    "version": "v0"
+  },
+  "servers": [
+    {
+      "url": "http://localhost",
+      "description": "Generated server url"
+    }
+  ],
+  "paths": {
+    "/test1": {
+      "get": {
+        "tags": [
+          "basic-controller"
+        ],
+        "summary": "get1",
+        "description": "Provides an animal.",
+        "operationId": "get1",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "oneOf": [
+                    {
+                      "$ref": "#/components/schemas/Cat"
+                    },
+                    {
+                      "$ref": "#/components/schemas/Dog"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Animal": {
+        "type": "object",
+        "description": "Represents an Animal class."
+      },
+      "Cat": {
+        "type": "object",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Animal"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "speed": {
+                "type": "integer",
+                "format": "int32"
+              }
+            }
+          }
+        ]
+      },
+      "Dog": {
+        "type": "object",
+        "description": "Represents a Dog class.",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Animal"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "age": {
+                "type": "integer",
+                "format": "int32"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}