feat(json): add config to SchemaIntrospector, implement custom annotation description extraction for SerializationClassJsonSchemaGenerator (#196)

## Description
Added generic `config` field to `SchemaIntrospector` interface to allow
customizing schema introspection. Added `DescriptionExtractor`
functional interface to allow customizing property/type description
extraction logic. Added config for
`SerializationClassSchemaIntrospector` to allow processing custom
description annotations

**Related Issues:** closes #193

Author: EugeneTheDev

kotlinx-schema-generator-core/src/commonMain/kotlin/kotlinx/schema/generator/core/AbstractSchemaGenerator.kt

@@ -8,12 +8,13 @@ import kotlinx.schema.generator.core.ir.TypeGraphTransformer
  *
  * @param T the type of the object for which the schema is being generated
  * @param R the type of the resulting schema representation
+ * @param C the type of the configuration used by the introspector
  * @property introspector the component responsible for introspecting the input and producing a type graph
  * @property typeGraphTransformer the component responsible for converting the type graph
  * into the desired schema representation
  */
-public abstract class AbstractSchemaGenerator<T : Any, R : Any>(
-    protected val introspector: SchemaIntrospector<T>,
+public abstract class AbstractSchemaGenerator<T : Any, R : Any, C : Any>(
+    protected val introspector: SchemaIntrospector<T, C>,
     protected val typeGraphTransformer: TypeGraphTransformer<R, *>,
 ) : SchemaGenerator<T, R> {
     protected abstract fun getRootName(target: T): String

kotlinx-schema-generator-core/src/commonMain/kotlin/kotlinx/schema/generator/core/ir/Introspections.kt

@@ -114,3 +114,18 @@ public object Introspections {
             null
         }
 }
+
+/**
+ * Functional interface describing a strategy for extracting a property/type description from a list of annotations
+ * associated with it.
+ * It's used to allow custom description annotations.
+ */
+public fun interface DescriptionExtractor {
+    /**
+     * Extracts a description from a list of annotations.
+     *
+     * @param annotations List of annotations to inspect for a description
+     * @return The description text if found, or null if no description is present
+     */
+    public fun extract(annotations: List<Annotation>): String?
+}

kotlinx-schema-generator-core/src/commonMain/kotlin/kotlinx/schema/generator/core/ir/SchemaIntrospector.kt

@@ -12,6 +12,11 @@ package kotlinx.schema.generator.core.ir
  * 5. Introspectors instantiate context and call `toRef()` / `convertToTypeRef()`
  * 6. Return TypeGraph(root, context.nodes)
  */
-public interface SchemaIntrospector<T> {
+public interface SchemaIntrospector<T, C> {
+    /**
+     * Configuration object for the introspector
+     */
+    public val config: C
+
     public fun introspect(root: T): TypeGraph
 }

kotlinx-schema-generator-core/src/jvmMain/kotlin/kotlinx/schema/generator/reflect/ReflectionClassIntrospector.kt

@@ -29,7 +29,9 @@ import kotlin.reflect.KProperty
  * - Requires classes to have a primary constructor
  * - Type parameters are not fully supported
  */
-public object ReflectionClassIntrospector : SchemaIntrospector<KClass<*>> {
+public object ReflectionClassIntrospector : SchemaIntrospector<KClass<*>, Unit> {
+    override val config: Unit = Unit
+
     override fun introspect(root: KClass<*>): TypeGraph {
         val context = IntrospectionContext()
         val rootRef = context.convertToTypeRef(root)

kotlinx-schema-generator-core/src/jvmMain/kotlin/kotlinx/schema/generator/reflect/ReflectionFunctionIntrospector.kt

@@ -22,7 +22,9 @@ import kotlin.reflect.KParameter
  * val typeGraph = ReflectionFunctionIntrospector.introspect(::myFunction)
  * ```
  */
-public object ReflectionFunctionIntrospector : SchemaIntrospector<KCallable<*>> {
+public object ReflectionFunctionIntrospector : SchemaIntrospector<KCallable<*>, Unit> {
+    override val config: Unit = Unit
+
     override fun introspect(root: KCallable<*>): TypeGraph {
         require(!root.isSuspend) { "Suspend functions are not supported" }
         require(root.parameters.none { it.kind == KParameter.Kind.EXTENSION_RECEIVER }) {

kotlinx-schema-generator-core/src/jvmTest/kotlin/kotlinx/schema/generator/core/AbstractSchemaGeneratorTest.kt

@@ -15,22 +15,22 @@ import kotlin.reflect.KClass
 @ExtendWith(MockKExtension::class)
 class AbstractSchemaGeneratorTest {
     @MockK
-    private lateinit var introspector: SchemaIntrospector<KClass<*>>
+    private lateinit var introspector: SchemaIntrospector<KClass<*>, Unit>
 
     @MockK
     private lateinit var emitter: TypeGraphTransformer<Map<String, String>, *>
 
     @MockK
     private lateinit var typeGraph: TypeGraph
 
-    private lateinit var generator: AbstractSchemaGenerator<KClass<*>, Map<String, String>>
+    private lateinit var generator: AbstractSchemaGenerator<KClass<*>, Map<String, String>, Unit>
 
     private val rootName = AbstractSchemaGeneratorTest::class.qualifiedName!!
 
     @BeforeEach
     fun setUp() {
         generator =
-            object : AbstractSchemaGenerator<KClass<*>, Map<String, String>>(introspector, emitter) {
+            object : AbstractSchemaGenerator<KClass<*>, Map<String, String>, Unit>(introspector, emitter) {
                 override fun getRootName(target: KClass<*>): String = requireNotNull(target.qualifiedName)
 
                 override fun targetType(): KClass<KClass<*>> = KClass::class

kotlinx-schema-generator-json/src/commonMain/kotlin/kotlinx/schema/generator/json/serialization/SerializationClassJsonSchemaGenerator.kt

@@ -16,29 +16,28 @@ import kotlin.reflect.KClass
  * with a configurable `JsonSchemaConfig` to define schema generation behavior.
  *
  * @constructor Creates an instance of `SerializationClassJsonSchemaGenerator`.
- * @param config Configuration for generating JSON Schemas, such as formatting details
+ * @param json The [Json] instance used for serializing schema objects.
+ * @param introspectorConfig Configuration for introspecting serial descriptors.
+ * @param jsonSchemaConfig Configuration for generating JSON Schemas, such as formatting details
  * and handling of optional nullable properties. Defaults to [JsonSchemaConfig.Default].
  */
 public class SerializationClassJsonSchemaGenerator(
-    private val json: Json,
-    config: JsonSchemaConfig,
-) : AbstractSchemaGenerator<SerialDescriptor, JsonSchema>(
-        introspector = SerializationClassSchemaIntrospector(json),
+    private val json: Json =
+        Json {
+            encodeDefaults = false
+            classDiscriminator = "type"
+            classDiscriminatorMode = kotlinx.serialization.json.ClassDiscriminatorMode.ALL_JSON_OBJECTS
+        },
+    introspectorConfig: SerializationClassSchemaIntrospector.Config = SerializationClassSchemaIntrospector.Config(),
+    jsonSchemaConfig: JsonSchemaConfig = JsonSchemaConfig.Default,
+) : AbstractSchemaGenerator<SerialDescriptor, JsonSchema, SerializationClassSchemaIntrospector.Config>(
+        introspector = SerializationClassSchemaIntrospector(introspectorConfig, json),
         typeGraphTransformer =
             TypeGraphToJsonSchemaTransformer(
-                config = config,
+                config = jsonSchemaConfig,
                 json = json,
             ),
     ) {
-    public constructor() : this(
-        json = Json {
-            encodeDefaults = false
-            classDiscriminator = "type"
-            classDiscriminatorMode = kotlinx.serialization.json.ClassDiscriminatorMode.ALL_JSON_OBJECTS
-        },
-        config = JsonSchemaConfig.Default,
-    )
-
     override fun getRootName(target: SerialDescriptor): String = target.serialName
 
     override fun targetType(): KClass<SerialDescriptor> = SerialDescriptor::class
@@ -56,14 +55,6 @@ public class SerializationClassJsonSchemaGenerator(
          * kotlinx.serialization descriptors. It simplifies the creation of schemas
          * without requiring explicit configuration.
          */
-        public val Default: SerializationClassJsonSchemaGenerator =
-            SerializationClassJsonSchemaGenerator(
-                json = Json {
-                    encodeDefaults = false
-                    classDiscriminator = "type"
-                    classDiscriminatorMode = kotlinx.serialization.json.ClassDiscriminatorMode.ALL_JSON_OBJECTS
-                },
-                config = JsonSchemaConfig.Default,
-            )
+        public val Default: SerializationClassJsonSchemaGenerator = SerializationClassJsonSchemaGenerator()
     }
 }

kotlinx-schema-generator-json/src/commonMain/kotlin/kotlinx/schema/generator/json/serialization/SerializationClassSchemaIntrospector.kt

@@ -1,5 +1,6 @@
 package kotlinx.schema.generator.json.serialization
 
+import kotlinx.schema.generator.core.ir.DescriptionExtractor
 import kotlinx.schema.generator.core.ir.SchemaIntrospector
 import kotlinx.schema.generator.core.ir.TypeGraph
 import kotlinx.serialization.descriptors.SerialDescriptor
@@ -15,20 +16,26 @@ import kotlinx.serialization.json.Json
  *                Defaults to a Json instance with encodeDefaults = false.
  */
 public class SerializationClassSchemaIntrospector(
-    private val json: Json = Json {
-        encodeDefaults = false
-        classDiscriminator = "type"
-        classDiscriminatorMode = kotlinx.serialization.json.ClassDiscriminatorMode.ALL_JSON_OBJECTS
-    },
-) : SchemaIntrospector<SerialDescriptor> {
+    override val config: Config = Config(),
+    private val json: Json =
+        Json {
+            encodeDefaults = false
+            classDiscriminator = "type"
+            classDiscriminatorMode = kotlinx.serialization.json.ClassDiscriminatorMode.ALL_JSON_OBJECTS
+        },
+) : SchemaIntrospector<SerialDescriptor, SerializationClassSchemaIntrospector.Config> {
+    public data class Config(
+        val descriptionExtractor: DescriptionExtractor = DescriptionExtractor { null },
+    )
+
     /**
      * Introspects a serial descriptor into a [TypeGraph].
      *
      * @param root The root serial descriptor to introspect
      * @return A TypeGraph containing the root type reference and all discovered type nodes
      */
     public override fun introspect(root: SerialDescriptor): TypeGraph {
-        val context = SerializationIntrospectionContext(json)
+        val context = SerializationIntrospectionContext(json, config)
         val rootRef = context.toRef(root)
         return TypeGraph(root = rootRef, nodes = context.nodes())
     }

kotlinx-schema-generator-json/src/commonMain/kotlin/kotlinx/schema/generator/json/serialization/SerializationIntrospectionContext.kt

@@ -36,6 +36,7 @@ import kotlinx.serialization.descriptors.PrimitiveKind as SerialPrimitiveKind
 @OptIn(InternalSchemaGeneratorApi::class)
 internal class SerializationIntrospectionContext(
     private val json: Json,
+    private val config: SerializationClassSchemaIntrospector.Config,
 ) : BaseIntrospectionContext<SerialDescriptor, SerialDescriptor>() {
     /**
      * Returns the discovered type nodes.
@@ -356,26 +357,18 @@ internal class SerializationIntrospectionContext(
     private fun descriptorId(descriptor: SerialDescriptor): TypeId = TypeId(descriptor.serialName)
 
     /**
-     * Extracts the @Description annotation value from a descriptor's annotations.
+     * Extracts description from a list of type annotations.
      */
     private fun extractDescription(descriptor: SerialDescriptor): String? =
-        descriptor.annotations
-            .filterIsInstance<Description>()
-            .firstOrNull()
-            ?.value
+        config.descriptionExtractor.extract(descriptor.annotations)
 
     /**
-     * Extracts the @Description annotation value from a descriptor element's annotations.
+     * Extracts description from a list of element annotations.
      */
     private fun extractElementDescription(
         descriptor: SerialDescriptor,
         index: Int,
-    ): String? =
-        descriptor
-            .getElementAnnotations(index)
-            .filterIsInstance<Description>()
-            .firstOrNull()
-            ?.value
+    ): String? = config.descriptionExtractor.extract(descriptor.getElementAnnotations(index))
 
     /**
      * Returns a new [TypeRef] with the specified nullable flag.

kotlinx-schema-generator-json/src/commonTest/kotlin/kotlinx/schema/generator/json/serialization/SerializationClassJsonSchemaGeneratorTest.kt

@@ -2,13 +2,18 @@ package kotlinx.schema.generator.json.serialization
 
 import io.kotest.assertions.json.shouldEqualJson
 import kotlinx.schema.json.encodeToString
+import kotlinx.serialization.SerialInfo
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.Json
 import kotlin.test.Test
 
 class SerializationClassJsonSchemaGeneratorTest {
+    @SerialInfo
+    annotation class CustomDescription(val value: String)
+
     @Serializable
     data class Person(
+        @property:CustomDescription("First name")
         val firstName: String,
     )
 
@@ -22,14 +27,21 @@ class SerializationClassJsonSchemaGeneratorTest {
           "type": "object",
           "properties": {
             "firstName": {
-              "type": "string"
+              "type": "string",
+              "description": "First name"
             }
           },
           "additionalProperties": false
         }
         """
 
-    val generator = SerializationClassJsonSchemaGenerator()
+    val generator = SerializationClassJsonSchemaGenerator(
+        introspectorConfig = SerializationClassSchemaIntrospector.Config(
+            descriptionExtractor = { annotations ->
+                annotations.filterIsInstance<CustomDescription>().firstOrNull()?.value
+            },
+        ),
+    )
 
     @Test
     fun `Should generate JsonSchema from SerialDescriptor`() {