Support for nullable request parameters in Kotlin. Fixes #2006

Author: bnasslahsen

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

@@ -1,6 +1,7 @@
 package org.springdoc.core.configuration
 
 import com.fasterxml.jackson.module.kotlin.KotlinModule
+import io.swagger.v3.oas.annotations.Parameter
 import io.swagger.v3.oas.models.media.ByteArraySchema
 import org.springdoc.core.customizers.ParameterCustomizer
 import org.springdoc.core.parsers.KotlinCoroutinesReturnTypeParser
@@ -14,6 +15,7 @@ import org.springframework.context.annotation.Bean
 import org.springframework.context.annotation.Configuration
 import org.springframework.context.annotation.Lazy
 import org.springframework.core.MethodParameter
+import org.springframework.core.annotation.AnnotatedElementUtils
 import kotlin.coroutines.Continuation
 import kotlin.reflect.KParameter
 import kotlin.reflect.jvm.kotlinFunction
@@ -60,13 +62,25 @@ open class SpringDocKotlinConfiguration(objectMapperProvider: ObjectMapperProvid
 	 */
 	@Bean
 	@Lazy(false)
+	@ConditionalOnProperty(
+		name = [Constants.SPRINGDOC_NULLABLE_REQUEST_PARAMETER_ENABLED],
+		matchIfMissing = true
+	)
 	@ConditionalOnMissingBean
 	open fun nullableKotlinRequestParameterCustomizer(): ParameterCustomizer {
 		return ParameterCustomizer { parameterModel, methodParameter ->
 			if (parameterModel == null) return@ParameterCustomizer null
 			val kParameter = methodParameter.toKParameter()
 			if (kParameter != null) {
-				parameterModel.required = kParameter.type.isMarkedNullable == false
+				val parameterDoc = AnnotatedElementUtils.findMergedAnnotation(
+					AnnotatedElementUtils.forAnnotations(*methodParameter.parameterAnnotations),
+					Parameter::class.java
+				)
+				// Swagger @Parameter annotation takes precedence
+				if (parameterDoc != null && parameterDoc.required)
+					parameterModel.required = parameterDoc.required
+				else
+					parameterModel.required = kParameter.type.isMarkedNullable == false
 			}
 			return@ParameterCustomizer parameterModel
 		}

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/properties/SpringDocConfigProperties.java

@@ -42,6 +42,7 @@
 
 /**
  * The type Spring doc config properties.
+ *
  * @author bnasslahsen
  */
 @Lazy(false)
@@ -236,6 +237,47 @@ public class SpringDocConfigProperties {
 	 */
 	private SortConverter sortConverter = new SortConverter();
 
+	/**
+	 * The Nullable request parameter enabled.
+	 */
+	private boolean nullableRequestParameterEnabled;
+
+	/**
+	 * Gets override with generic response.
+	 *
+	 * @return the override with generic response
+	 */
+	public Boolean getOverrideWithGenericResponse() {
+		return overrideWithGenericResponse;
+	}
+
+	/**
+	 * Sets override with generic response.
+	 *
+	 * @param overrideWithGenericResponse the override with generic response
+	 */
+	public void setOverrideWithGenericResponse(Boolean overrideWithGenericResponse) {
+		this.overrideWithGenericResponse = overrideWithGenericResponse;
+	}
+
+	/**
+	 * Is nullable request parameter enabled boolean.
+	 *
+	 * @return the boolean
+	 */
+	public boolean isNullableRequestParameterEnabled() {
+		return nullableRequestParameterEnabled;
+	}
+
+	/**
+	 * Sets nullable request parameter enabled.
+	 *
+	 * @param nullableRequestParameterEnabled the nullable request parameter enabled
+	 */
+	public void setNullableRequestParameterEnabled(boolean nullableRequestParameterEnabled) {
+		this.nullableRequestParameterEnabled = nullableRequestParameterEnabled;
+	}
+
 	/**
 	 * Is default support form data boolean.
 	 *
@@ -936,6 +978,7 @@ public void setPreLoadingEnabled(boolean preLoadingEnabled) {
 
 	/**
 	 * The type Model converters.
+	 *
 	 * @author bnasslashen
 	 */
 	public static class ModelConverters {
@@ -1012,6 +1055,7 @@ public void setPolymorphicConverter(PolymorphicConverter polymorphicConverter) {
 
 		/**
 		 * The type Deprecating converter.
+		 *
 		 * @author bnasslashen
 		 */
 		public static class DeprecatingConverter {
@@ -1072,6 +1116,7 @@ public void setEnabled(boolean enabled) {
 
 		/**
 		 * The type Pageable converter.
+		 *
 		 * @author bnasslashen
 		 */
 		public static class PageableConverter {
@@ -1103,6 +1148,7 @@ public void setEnabled(boolean enabled) {
 
 	/**
 	 * The type Sort converter.
+	 *
 	 * @author daniel -shuy
 	 */
 	public static class SortConverter {
@@ -1133,6 +1179,7 @@ public void setEnabled(boolean enabled) {
 
 	/**
 	 * The type Webjars.
+	 *
 	 * @author bnasslahsen
 	 */
 	public static class Webjars {
@@ -1162,6 +1209,7 @@ public void setPrefix(String prefix) {
 
 	/**
 	 * The type Api docs.
+	 *
 	 * @author bnasslahsen
 	 */
 	public static class ApiDocs {
@@ -1285,11 +1333,11 @@ public void setVersion(OpenApiVersion version) {
 		 */
 		public enum OpenApiVersion {
 			/**
-			 *Openapi 3.0.1 version.
+			 * Openapi 3.0.1 version.
 			 */
 			OPENAPI_3_0("3.0.1"),
 			/**
-			 *Openapi 3.1.0 version.
+			 * Openapi 3.1.0 version.
 			 */
 			OPENAPI_3_1("3.1.0");
 
@@ -1320,6 +1368,7 @@ public String getVersion() {
 
 	/**
 	 * The type Groups.
+	 *
 	 * @author bnasslahsen
 	 */
 	public static class Groups {
@@ -1350,6 +1399,7 @@ public void setEnabled(boolean enabled) {
 
 	/**
 	 * The type Cache.
+	 *
 	 * @author bnasslahsen
 	 */
 	public static class Cache {
@@ -1379,6 +1429,7 @@ public void setDisabled(boolean disabled) {
 
 	/**
 	 * The type Group config.
+	 *
 	 * @author bnasslahsen
 	 */
 	public static class GroupConfig {

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

@@ -395,6 +395,10 @@ public final class Constants {
 	 */
 	public static final String SPRINGDOC_SORT_CONVERTER_ENABLED = "springdoc.model-converters.sort-converter.enabled";
 
+	/**
+	 * The constant SPRINGDOC_NULLABLE_REQUEST_PARAMETER_ENABLED.
+	 */
+	public static final String SPRINGDOC_NULLABLE_REQUEST_PARAMETER_ENABLED = "springdoc.nullable-request-parameter-enabled";
 	/**
 	 * Instantiates a new Constants.
 	 */

springdoc-openapi-tests/springdoc-openapi-kotlin-tests/src/test/kotlin/test/org/springdoc/api/app7/ExampleController.kt

@@ -1,5 +1,6 @@
 package test.org.springdoc.api.app7
 
+import io.swagger.v3.oas.annotations.Parameter
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.RequestMapping
 import org.springframework.web.bind.annotation.RequestParam
@@ -11,4 +12,7 @@ data class Greeting(val greeting: String)
 interface ExampleController {
     @GetMapping("/")
     fun greet(@RequestParam name: String?): Greeting
+
+	@GetMapping("/test")
+	fun test(@RequestParam @Parameter(required = true) name: String?): Greeting
 }

springdoc-openapi-tests/springdoc-openapi-kotlin-tests/src/test/kotlin/test/org/springdoc/api/app8/ExampleController.kt

@@ -0,0 +1,17 @@
+package test.org.springdoc.api.app8
+
+import io.swagger.v3.oas.annotations.Parameter
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.RequestParam
+import org.springframework.web.bind.annotation.RestController
+
+data class Greeting(val greeting: String)
+
+@RestController
+interface ExampleController {
+    @GetMapping("/")
+    fun greet(@RequestParam name: String?): Greeting
+
+	@GetMapping("/test")
+	fun test(@RequestParam @Parameter(required = true) name: String?): Greeting
+}

springdoc-openapi-tests/springdoc-openapi-kotlin-tests/src/test/kotlin/test/org/springdoc/api/app8/SpringDocApp8Test.kt

@@ -0,0 +1,49 @@
+/*
+ *
+ *  * Copyright 2019-2020 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.app8
+
+import org.springdoc.core.utils.Constants
+import org.springframework.aop.framework.ProxyFactory
+import org.springframework.boot.autoconfigure.SpringBootApplication
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.ComponentScan
+import org.springframework.context.support.GenericApplicationContext
+import org.springframework.test.context.TestPropertySource
+import test.org.springdoc.api.AbstractKotlinSpringDocTest
+
+@TestPropertySource(properties =  [Constants.SPRINGDOC_NULLABLE_REQUEST_PARAMETER_ENABLED+"=false"])
+class SpringDocApp8Test : AbstractKotlinSpringDocTest() {
+
+	@SpringBootApplication
+	@ComponentScan(basePackages = ["org.springdoc", "test.org.springdoc.api.app8"])
+	class DemoApplication{
+		@Bean
+		fun controller(applicationContext: GenericApplicationContext): ExampleController {
+			return createProxy(ExampleController::class.java)
+		}
+
+		private fun <T> createProxy(clazz: Class<T>): T {
+			val proxyFactory = ProxyFactory(clazz)
+			proxyFactory.targetClass = clazz
+			@Suppress("UNCHECKED_CAST")
+			return proxyFactory.proxy as T
+		}
+	}
+
+}

springdoc-openapi-tests/springdoc-openapi-kotlin-tests/src/test/resources/results/app7.json

@@ -40,6 +40,36 @@
           }
         }
       }
+    },
+    "/test": {
+      "get": {
+        "tags": [
+          "example-controller"
+        ],
+        "operationId": "test",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/Greeting"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {

springdoc-openapi-tests/springdoc-openapi-kotlin-tests/src/test/resources/results/app8.json

@@ -0,0 +1,90 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "OpenAPI definition",
+    "version": "v0"
+  },
+  "servers": [
+    {
+      "url": "",
+      "description": "Generated server url"
+    }
+  ],
+  "paths": {
+    "/": {
+      "get": {
+        "tags": [
+          "example-controller"
+        ],
+        "operationId": "greet",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/Greeting"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/test": {
+      "get": {
+        "tags": [
+          "example-controller"
+        ],
+        "operationId": "test",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/Greeting"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Greeting": {
+        "required": [
+          "greeting"
+        ],
+        "type": "object",
+        "properties": {
+          "greeting": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}