KTOR-9451 Support nested generic types (#5500)

* KTOR-9451 Support nested generic types

* fixup! KTOR-9451 Support nested generic types

Author: bjhham

ktor-shared/ktor-openapi-schema/common/src/io/ktor/openapi/JsonSchemaInference.kt

@@ -77,8 +77,10 @@ public class KotlinxSerializerJsonSchemaInference(
         public val Default: KotlinxSerializerJsonSchemaInference =
             KotlinxSerializerJsonSchemaInference(EmptySerializersModule())
     }
+    private val kTypeLookup = mutableMapOf<String, KType>()
 
     override fun buildSchema(type: KType): JsonSchema {
+        includeKType(type)
         return buildSchemaFromDescriptor(
             module.serializer(type).descriptor,
             // parameterized types cannot be referenced from their serial name
@@ -87,29 +89,45 @@ public class KotlinxSerializerJsonSchemaInference(
         )
     }
 
+    private fun includeKType(type: KType) {
+        // use toString() because qualifiedName is unavailable in web
+        val qualifiedName = type.toString().substringBefore('<')
+        if (qualifiedName in kTypeLookup) return
+        kTypeLookup[qualifiedName] = type
+        for (typeArg in type.arguments) {
+            typeArg.type?.let(::includeKType)
+        }
+    }
+
+    private fun SerialDescriptor.isParameterized(): Boolean =
+        kTypeLookup[nonNullSerialName]?.arguments?.isNotEmpty() == true
+
     @OptIn(ExperimentalSerializationApi::class, InternalAPI::class)
     internal fun buildSchemaFromDescriptor(
         descriptor: SerialDescriptor,
-        includeTitle: Boolean = true,
+        includeTitle: Boolean = !descriptor.isParameterized(),
         includeAnnotations: List<Annotation> = emptyList(),
         visiting: MutableSet<String>,
     ): JsonSchema {
         val reflectJsonSchema: KClass<*>.() -> ReferenceOr<JsonSchema> = {
             Value(
-                module.serializer(this, emptyList(), false)
-                    .descriptor.buildJsonSchema(includeTitle, visiting = visiting)
+                buildSchemaFromDescriptor(
+                    descriptor = module.serializer(this, emptyList(), false).descriptor,
+                    includeTitle = includeTitle,
+                    visiting = visiting,
+                )
             )
         }
         val annotations = includeAnnotations + descriptor.annotations
         val isNullable = descriptor.isNullable
 
         // For inline descriptors, use the delegate descriptor
         if (descriptor.isInline) {
-            return descriptor.getElementDescriptor(0)
-                .buildJsonSchema(
-                    visiting = visiting,
-                    includeAnnotations = includeAnnotations
-                )
+            return buildSchemaFromDescriptor(
+                descriptor = descriptor.getElementDescriptor(0),
+                includeAnnotations = includeAnnotations,
+                visiting = visiting,
+            )
         }
 
         return when (descriptor.kind) {

ktor-shared/ktor-openapi-schema/ktor-openapi-schema-reflect/jvm/src/io/ktor/openapi/reflect/JsonSchemaInference.jvm.kt

@@ -12,6 +12,9 @@ import java.time.OffsetDateTime
 import kotlin.reflect.KClass
 import kotlin.reflect.KProperty1
 import kotlin.reflect.KType
+import kotlin.reflect.KTypeParameter
+import kotlin.reflect.KTypeProjection
+import kotlin.reflect.full.createType
 import kotlin.reflect.full.isSubclassOf
 import kotlin.reflect.full.memberProperties
 import kotlin.reflect.full.primaryConstructor
@@ -139,7 +142,7 @@ public class ReflectionJsonSchemaInference(
 
         // Value classes (inline) should be represented as their underlying value
         if (kClass.isValue) {
-            kClass.underlyingValueClassTypeOrNull()?.let { underlyingType ->
+            kClass.underlyingValueClassTypeOrNull(type)?.let { underlyingType ->
                 val unboxedSchema = buildSchemaInternal(
                     underlyingType,
                     visiting,
@@ -236,9 +239,10 @@ public class ReflectionJsonSchemaInference(
                 if (adapter.isIgnored(prop)) continue
 
                 val propertyName = adapter.getName(prop)
-                val propertyIsNullable = adapter.isNullable(prop.returnType)
+                val resolvedPropertyType = swapTypeArgs(prop.returnType, type)
+                val propertyIsNullable = adapter.isNullable(resolvedPropertyType)
 
-                properties[propertyName] = buildSchemaOrRef(prop.returnType, visiting, prop.annotations)
+                properties[propertyName] = buildSchemaOrRef(resolvedPropertyType, visiting, prop.annotations)
 
                 // Required: non-nullable properties are required (best effort; default values are not detectable reliably)
                 if (!propertyIsNullable) {
@@ -288,6 +292,48 @@ public class ReflectionJsonSchemaInference(
         }
     }
 
+    private fun KClass<*>.underlyingValueClassTypeOrNull(ownerType: KType): KType? {
+        val ctorParam = primaryConstructor?.parameters?.singleOrNull()
+            ?: return null
+
+        val propType = memberProperties.firstOrNull { it.name == ctorParam.name }?.returnType
+            ?: ctorParam.type
+
+        return swapTypeArgs(propType, ownerType)
+    }
+
+    private fun swapTypeArgs(propertyType: KType, ownerType: KType): KType {
+        val ownerClass = ownerType.classifier as? KClass<*> ?: return propertyType
+        val typeParameters = ownerClass.typeParameters
+        if (typeParameters.isEmpty() || ownerType.arguments.isEmpty()) return propertyType
+
+        val substitution = typeParameters
+            .zip(ownerType.arguments)
+            .mapNotNull { (param, arg) -> arg.type?.let { param to it } }
+            .toMap()
+
+        if (substitution.isEmpty()) return propertyType
+
+        fun substitute(type: KType): KType {
+            val classifier = type.classifier
+            if (classifier is KTypeParameter) {
+                return substitution[classifier] ?: type
+            }
+
+            val kClass = classifier as? KClass<*> ?: return type
+            if (type.arguments.isEmpty()) return type
+
+            val newArgs = type.arguments.map { projection ->
+                val argType = projection.type ?: return@map projection
+                KTypeProjection(projection.variance, substitute(argType))
+            }
+
+            return kClass.createType(newArgs, type.isMarkedNullable)
+        }
+
+        return substitute(propertyType)
+    }
+
     @OptIn(
         ExperimentalTime::class,
         ExperimentalUuidApi::class,
@@ -376,15 +422,6 @@ public class ReflectionJsonSchemaInference(
         else -> null
     }
 
-    private fun KClass<*>.underlyingValueClassTypeOrNull(): KType? {
-        val ctorParam = primaryConstructor?.parameters?.singleOrNull()
-            ?: return null
-
-        // Prefer the backing property type when available (better chance of having resolved type args)
-        val propType = memberProperties.firstOrNull { it.name == ctorParam.name }?.returnType
-        return propType ?: ctorParam.type
-    }
-
     private fun KClass<*>.starProjectedTypeOrNull(): KType? = try {
         @Suppress("UNCHECKED_CAST")
         (this as KClass<Any>).starProjectedType

ktor-shared/ktor-openapi-schema/ktor-openapi-schema-reflect/jvm/test-resources/schema/Response.yaml

@@ -0,0 +1,27 @@
+type: object
+required:
+  - data
+properties:
+  data:
+    type: object
+    required:
+      - items
+      - total
+    properties:
+      items:
+        type: array
+        items:
+          type: object
+          title: io.ktor.openapi.reflect.Country
+          required:
+            - name
+            - code
+          properties:
+            name:
+              type: string
+              pattern: '[A-Za-z''-,]+'
+            code:
+              type: string
+              pattern: '[A-Z]{3}'
+      total:
+        type: integer

ktor-shared/ktor-openapi-schema/ktor-openapi-schema-reflect/jvm/test/io/ktor/openapi/reflect/AbstractSchemaInferenceTest.kt

@@ -196,6 +196,10 @@ abstract class AbstractSchemaInferenceTest(
     fun `value classes`() =
         assertSchemaMatches<Email>()
 
+    @Test
+    fun `nested generics`() =
+        assertSchemaMatches<Response<Page<Country>>>()
+
     private inline fun <reified T : Any> assertSchemaMatches() {
         val schema = inference.jsonSchema<T>()
         val expected = readSchemaYaml<T>()
@@ -357,3 +361,14 @@ data class IntLiteral(val value: Int) : Expression
 
 @Serializable
 data class StringLiteral(val value: String) : Expression
+
+@Serializable
+data class Response<T>(
+    val data: T
+)
+
+@Serializable
+data class Page<out E>(
+    val items: List<E>,
+    val total: Int,
+)