improve javadoc in dsl

SMILEY4 · Jul 11, 2024 · 340094a · 340094a
1 parent cbd97bf
commit 340094a
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 2 deletions.
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/ExampleConfig.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/ExampleConfig.kt
@@ -14,12 +14,26 @@ class ExampleConfig {
     val sharedExamples = mutableMapOf<String, ExampleDescriptor>()
     var exampleEncoder: ExampleEncoder? = null
 
+
+    /**
+     * Add a shared example that can be referenced by all routes.
+     * The name of the example has to be unique among all shared examples and acts as its id.
+     * @param example the example data.
+     */
     fun example(example: ExampleDescriptor) {
         sharedExamples[example.name] = example
     }
 
+    /**
+     * Add a shared example that can be referenced by all routes by the given name.
+     * The provided name has to be unique among all shared examples and acts as its id.
+     */
     fun example(name: String, example: Example) = example(SwaggerExampleDescriptor(name, example))
 
+    /**
+     * Add a shared example that can be referenced by all routes by the given name.
+     * The provided name has to be unique among all shared examples and acts as its id.
+     */
     fun example(name: String, example: ValueExampleDescriptorDsl.() -> Unit) = example(
         ValueExampleDescriptorDsl()
             .apply(example)
@@ -33,6 +47,10 @@ class ExampleConfig {
             }
     )
 
+
+    /**
+     * Specify a custom encoder for example objects
+     */
     fun encoder(exampleEncoder: ExampleEncoder) {
         this.exampleEncoder = exampleEncoder
     }

diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/SchemaConfig.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/SchemaConfig.kt
@@ -13,32 +13,69 @@ import kotlin.reflect.typeOf
 @OpenApiDslMarker
 class SchemaConfig {
 
+    /**
+     * The json-schema generator for all schemas. See https://github.com/SMILEY4/schema-kenerator/wiki for more information.
+     */
     var generator: (type: KType) -> CompiledSwaggerSchema = SchemaConfigData.DEFAULT.generator
 
-    val schemas = mutableMapOf<String, TypeDescriptor>()
+    private val schemas = mutableMapOf<String, TypeDescriptor>()
 
-    val overwrite = mutableMapOf<KType, TypeDescriptor>()
+    private val overwrite = mutableMapOf<KType, TypeDescriptor>()
 
+
+    /**
+     * Overwrite the given [type] with the given [replacement]. When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     fun overwrite(type: KType, replacement: TypeDescriptor) {
         overwrite[type] = replacement
     }
 
+    /**
+     * Overwrite the given type [T] with the given [replacement]. When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     inline fun <reified T> overwrite(replacement: TypeDescriptor) = overwrite(typeOf<T>(), replacement)
 
+    /**
+     * Overwrite the given type [T] with the given [replacement]. When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     inline fun <reified T> overwrite(replacement: Schema<*>) = overwrite(typeOf<T>(), SwaggerTypeDescriptor(replacement))
 
+    /**
+     * Overwrite the given type [T] with the given [replacement]. When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     inline fun <reified T> overwrite(replacement: KType) = overwrite(typeOf<T>(), KTypeDescriptor(replacement))
 
+    /**
+     * Overwrite the given type [T] with the given replacement [R]. When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     inline fun <reified T, reified R> overwrite() = overwrite(typeOf<T>(), KTypeDescriptor(typeOf<R>()))
 
+
+    /**
+     * Add a shared schema that can be referenced by all routes by the given id.
+     */
     fun schema(schemaId: String, descriptor: TypeDescriptor) {
         schemas[schemaId] = descriptor
     }
 
+    /**
+     * Add a shared schema that can be referenced by all routes by the given id.
+     */
     fun schema(schemaId: String, schema: Schema<*>) = schema(schemaId, SwaggerTypeDescriptor(schema))
 
+    /**
+     * Add a shared schema that can be referenced by all routes by the given id.
+     */
     fun schema(schemaId: String, schema: KType) = schema(schemaId, KTypeDescriptor(schema))
 
+    /**
+     * Add a shared schema that can be referenced by all routes by the given id.
+     */
     inline fun <reified T> schema(schemaId: String) = schema(schemaId, KTypeDescriptor(typeOf<T>()))
 
     fun build(securityConfig: SecurityData) = SchemaConfigData(