Skip to content

Commit 608c36c

Browse files
thejeff77thejeff77
committed
feat: auto-set nullable: true for Kotlin nullable types in schema properties
Springdoc correctly uses Kotlin reflection to detect nullable types (isMarkedNullable) for the required list — nullable fields are excluded from `required`. However, it does not set `nullable: true` on the property schema itself. This causes OpenAPI client generators (e.g., fabrikt, openapi-generator) to produce non-null types with null defaults, which fails Kotlin compilation. Adds KotlinNullablePropertyCustomizer that inspects Kotlin data class properties via kotlin-reflect and sets nullable: true on schema properties whose return type is marked nullable. Auto-registered in SpringDocKotlinConfiguration when kotlin-reflect is on the classpath. Fixes: #906
1 parent 9330daf commit 608c36c

5 files changed

Lines changed: 213 additions & 0 deletions

File tree

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ package org.springdoc.core.configuration
2828

2929
import org.springdoc.core.converters.KotlinInlineClassUnwrappingConverter
3030
import org.springdoc.core.customizers.KotlinDeprecatedPropertyCustomizer
31+
import org.springdoc.core.customizers.KotlinNullablePropertyCustomizer
3132
import org.springdoc.core.providers.ObjectMapperProvider
3233
import org.springdoc.core.utils.Constants
3334
import org.springdoc.core.utils.SpringDocKotlinUtils
@@ -77,6 +78,13 @@ class SpringDocKotlinConfiguration() {
7778
return KotlinDeprecatedPropertyCustomizer(objectMapperProvider)
7879
}
7980

81+
@Bean
82+
@Lazy(false)
83+
@ConditionalOnMissingBean
84+
fun kotlinNullablePropertyCustomizer(objectMapperProvider: ObjectMapperProvider): KotlinNullablePropertyCustomizer {
85+
return KotlinNullablePropertyCustomizer(objectMapperProvider)
86+
}
87+
8088
@Bean
8189
@Lazy(false)
8290
@ConditionalOnMissingBean

‎springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/KotlinNullablePropertyCustomizer.kt‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
/*
2+
*
3+
* *
4+
* * *
5+
* * * *
6+
* * * * *
7+
* * * * * * Copyright 2019-2026 the original author or authors.
8+
* * * * * *
9+
* * * * * * Licensed under the Apache License, Version 2.0 (the "License");
10+
* * * * * * you may not use this file except in compliance with the License.
11+
* * * * * * You may obtain a copy of the License at
12+
* * * * * *
13+
* * * * * * https://www.apache.org/licenses/LICENSE-2.0
14+
* * * * * *
15+
* * * * * * Unless required by applicable law or agreed to in writing, software
16+
* * * * * * distributed under the License is distributed on an "AS IS" BASIS,
17+
* * * * * * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
* * * * * * See the License for the specific language governing permissions and
19+
* * * * * * limitations under the License.
20+
* * * * *
21+
* * * *
22+
* * *
23+
* *
24+
*
25+
*/
26+
27+
package org.springdoc.core.customizers
28+
29+
import com.fasterxml.jackson.databind.JavaType
30+
import io.swagger.v3.core.converter.AnnotatedType
31+
import io.swagger.v3.core.converter.ModelConverter
32+
import io.swagger.v3.core.converter.ModelConverterContext
33+
import io.swagger.v3.oas.models.Components
34+
import io.swagger.v3.oas.models.media.Schema
35+
import org.springdoc.core.providers.ObjectMapperProvider
36+
import kotlin.reflect.full.memberProperties
37+
38+
/**
39+
* Sets `nullable: true` on schema properties for Kotlin data class fields
40+
* whose return type is marked nullable (`Type?`).
41+
*
42+
* Springdoc already uses Kotlin nullability to determine the `required` list
43+
* (via [org.springdoc.core.utils.SchemaUtils.fieldRequired]), but does not set
44+
* `nullable: true` on the property schema itself. This causes OpenAPI client
45+
* generators (e.g., fabrikt) to produce non-null types with null defaults,
46+
* which fails compilation in Kotlin.
47+
*
48+
* See: https://github.com/springdoc/springdoc-openapi/issues/906
49+
*
50+
* @author Jeffrey Blayney
51+
*/
52+
class KotlinNullablePropertyCustomizer(
53+
private val objectMapperProvider: ObjectMapperProvider
54+
) : ModelConverter {
55+
56+
override fun resolve(
57+
type: AnnotatedType,
58+
context: ModelConverterContext,
59+
chain: Iterator<ModelConverter>
60+
): Schema<*>? {
61+
if (!chain.hasNext()) return null
62+
val resolvedSchema = chain.next().resolve(type, context, chain)
63+
64+
val javaType: JavaType =
65+
objectMapperProvider.jsonMapper().constructType(type.type)
66+
if (javaType.rawClass.packageName.startsWith("java.")) {
67+
return resolvedSchema
68+
}
69+
70+
val kotlinClass = try {
71+
javaType.rawClass.kotlin
72+
} catch (_: Throwable) {
73+
return resolvedSchema
74+
}
75+
76+
for (prop in kotlinClass.memberProperties) {
77+
if (prop.returnType.isMarkedNullable) {
78+
val fieldName = prop.name
79+
if (resolvedSchema != null && resolvedSchema.`$ref` != null) {
80+
val schema =
81+
context.getDefinedModels()[resolvedSchema.`$ref`.substring(
82+
Components.COMPONENTS_SCHEMAS_REF.length
83+
)]
84+
schema?.properties?.get(fieldName)?.nullable = true
85+
} else {
86+
resolvedSchema?.properties?.get(fieldName)?.nullable = true
87+
}
88+
}
89+
}
90+
return resolvedSchema
91+
}
92+
}

‎springdoc-openapi-tests/springdoc-openapi-kotlin-webmvc-tests/src/test/kotlin/test/org/springdoc/api/v30/app18/NullableController.kt‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
package test.org.springdoc.api.v30.app18
2+
3+
import org.springframework.web.bind.annotation.GetMapping
4+
import org.springframework.web.bind.annotation.RestController
5+
6+
data class NullableFieldsResponse(
7+
val requiredField: String,
8+
val nullableString: String? = null,
9+
val nullableInt: Int? = null,
10+
val nullableNested: NestedObject? = null,
11+
)
12+
13+
data class NestedObject(
14+
val name: String,
15+
val description: String? = null,
16+
)
17+
18+
@RestController
19+
class NullableController {
20+
@GetMapping("/nullable")
21+
fun getNullableFields(): NullableFieldsResponse =
22+
NullableFieldsResponse(requiredField = "hello")
23+
}

‎springdoc-openapi-tests/springdoc-openapi-kotlin-webmvc-tests/src/test/kotlin/test/org/springdoc/api/v30/app18/SpringDocApp18Test.kt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
package test.org.springdoc.api.v30.app18
2+
3+
import org.springframework.boot.autoconfigure.SpringBootApplication
4+
import org.springframework.context.annotation.ComponentScan
5+
import test.org.springdoc.api.v30.AbstractKotlinSpringDocMVCTest
6+
7+
class SpringDocApp18Test : AbstractKotlinSpringDocMVCTest() {
8+
9+
@SpringBootApplication
10+
@ComponentScan(basePackages = ["org.springdoc", "test.org.springdoc.api.v30.app18"])
11+
class DemoApplication
12+
}

‎springdoc-openapi-tests/springdoc-openapi-kotlin-webmvc-tests/src/test/resources/results/3.0.1/app18.json‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
{
2+
"openapi": "3.0.1",
3+
"info": {
4+
"title": "OpenAPI definition",
5+
"version": "v0"
6+
},
7+
"servers": [
8+
{
9+
"url": "http://localhost",
10+
"description": "Generated server url"
11+
}
12+
],
13+
"paths": {
14+
"/nullable": {
15+
"get": {
16+
"tags": [
17+
"nullable-controller"
18+
],
19+
"operationId": "getNullableFields",
20+
"responses": {
21+
"200": {
22+
"description": "OK",
23+
"content": {
24+
"*/*": {
25+
"schema": {
26+
"$ref": "#/components/schemas/NullableFieldsResponse"
27+
}
28+
}
29+
}
30+
}
31+
}
32+
}
33+
}
34+
},
35+
"components": {
36+
"schemas": {
37+
"NestedObject": {
38+
"required": [
39+
"name"
40+
],
41+
"type": "object",
42+
"properties": {
43+
"name": {
44+
"type": "string"
45+
},
46+
"description": {
47+
"type": "string",
48+
"nullable": true
49+
}
50+
}
51+
},
52+
"NullableFieldsResponse": {
53+
"required": [
54+
"requiredField"
55+
],
56+
"type": "object",
57+
"properties": {
58+
"requiredField": {
59+
"type": "string"
60+
},
61+
"nullableString": {
62+
"type": "string",
63+
"nullable": true
64+
},
65+
"nullableInt": {
66+
"type": "integer",
67+
"format": "int32",
68+
"nullable": true
69+
},
70+
"nullableNested": {
71+
"nullable": true,
72+
"$ref": "#/components/schemas/NestedObject"
73+
}
74+
}
75+
}
76+
}
77+
}
78+
}

0 commit comments

Comments
 (0)