Merge pull request #53 from bherbst/model_description

Support model property descriptions

Author: Wicpar

src/main/kotlin/com/papsign/ktor/openapigen/annotations/properties/description/Description.kt

@@ -0,0 +1,10 @@
+package com.papsign.ktor.openapigen.annotations.properties.description
+
+import com.papsign.ktor.openapigen.schema.processor.SchemaProcessorAnnotation
+
+/**
+ * Property annotation for providing a description of a schema model property
+ */
+@Target(AnnotationTarget.PROPERTY)
+@SchemaProcessorAnnotation(DescriptionProcessor::class)
+annotation class Description(val value: String)

src/main/kotlin/com/papsign/ktor/openapigen/annotations/properties/description/DescriptionProcessor.kt

@@ -0,0 +1,12 @@
+package com.papsign.ktor.openapigen.annotations.properties.description
+
+import com.papsign.ktor.openapigen.model.schema.SchemaModel
+import com.papsign.ktor.openapigen.schema.processor.SchemaProcessor
+import kotlin.reflect.KType
+
+object DescriptionProcessor: SchemaProcessor<Description> {
+    override fun process(model: SchemaModel<*>, type: KType, annotation: Description): SchemaModel<*> {
+        model.description = annotation.value
+        return model
+    }
+}

src/main/kotlin/com/papsign/ktor/openapigen/model/schema/SchemaModel.kt

@@ -7,30 +7,34 @@ sealed class SchemaModel<T>: DataModel {
 
     abstract var example: T?
     abstract var examples: List<T>?
+    abstract var description: String?
 
     data class SchemaModelObj<T>(
         var properties: Map<String, SchemaModel<*>>,
         var required: List<String>,
         var nullable: Boolean = false,
         override var example: T? = null,
         override var examples: List<T>? = null,
-        var type: DataType = DataType.`object`
+        var type: DataType = DataType.`object`,
+        override var description: String? = null
     ) : SchemaModel<T>()
 
     data class SchemaModelMap<T : Map<String, U>, U>(
         var additionalProperties: SchemaModel<U>,
         var nullable: Boolean = false,
         override var example: T? = null,
         override var examples: List<T>? = null,
-        var type: DataType = DataType.`object`
+        var type: DataType = DataType.`object`,
+        override var description: String? = null
     ) : SchemaModel<T>()
 
     data class SchemaModelEnum<T>(
         var enum: List<String>,
         var nullable: Boolean = false,
         override var example: T? = null,
         override var examples: List<T>? = null,
-        var type: DataType = DataType.string
+        var type: DataType = DataType.string,
+        override var description: String? = null
     ) : SchemaModel<T>()
 
     data class SchemaModelArr<T>(
@@ -41,7 +45,8 @@ sealed class SchemaModel<T>: DataModel {
         var uniqueItems: Boolean? = null,
         var minItems: Int? = null,
         var maxItems: Int? = null,
-        var type: DataType = DataType.array
+        var type: DataType = DataType.array,
+        override var description: String? = null
     ) : SchemaModel<T>()
 
     data class SchemaModelLitteral<T>(
@@ -51,16 +56,19 @@ sealed class SchemaModel<T>: DataModel {
         var minimum: T? = null,
         var maximum: T? = null,
         override var example: T? = null,
-        override var examples: List<T>? = null
+        override var examples: List<T>? = null,
+        override var description: String? = null
     ) : SchemaModel<T>()
 
     data class SchemaModelRef<T>(override val `$ref`: String) : SchemaModel<T>(), RefModel<SchemaModel<T>> {
         override var example: T? = null
         override var examples: List<T>? = null
+        override var description: String? = null
     }
 
     data class OneSchemaModelOf<T>(val oneOf: List<SchemaModel<out T>>) : SchemaModel<T>() {
         override var example: T? = null
         override var examples: List<T>? = null
+        override var description: String? = null
     }
 }

src/test/kotlin/TestServer.kt

@@ -15,6 +15,7 @@ import com.papsign.ktor.openapigen.annotations.Response
 import com.papsign.ktor.openapigen.annotations.mapping.OpenAPIName
 import com.papsign.ktor.openapigen.annotations.parameters.HeaderParam
 import com.papsign.ktor.openapigen.annotations.parameters.PathParam
+import com.papsign.ktor.openapigen.annotations.properties.description.Description
 import com.papsign.ktor.openapigen.annotations.type.`object`.example.ExampleProvider
 import com.papsign.ktor.openapigen.annotations.type.`object`.example.WithExample
 import com.papsign.ktor.openapigen.interop.withAPI
@@ -222,7 +223,7 @@ object TestServer {
     data class StringParam(@PathParam("A simple String Param") val a: String)
 
     @Response("A String Response")
-    data class StringResponse(val str: String)
+    data class StringResponse(@Description("The string value") val str: String)
 
     data class NameParam(@HeaderParam("A simple Header Param") @OpenAPIName("X-NAME") val name: String)