Swagger Description inside Param extension for Security

core/src/main/kotlin/org/evomaster/core/problem/api/param/Param.kt

@@ -5,27 +5,44 @@ import org.evomaster.core.search.gene.Gene
 
 
 abstract class Param(
-        val name: String,
-        val genes : MutableList<Gene>
-) : StructuralElement(genes){
+    val name: String,
+    val genes: MutableList<Gene>
+) : StructuralElement(genes) {
+
+    /**
+     * Contains the description of the parameter.
+     * Parameter description can be only set once.
+     * If the parameter description is already set, it will throw
+     * an IllegalStateException.
+     */
+    var description: String? = null
+        set(value) {
+            if (!value.isNullOrEmpty()) {
+                if (field.isNullOrEmpty()) {
+                    field = value
+                } else {
+                    throw IllegalStateException("Parameter description is already set for $name")
+                }
+            }
+        }
 
     //TODO need refactoring. eg shared abstract class for cases in which only 1 gene for sure
     @Deprecated("Assumes there is only 1 gene. Rather use primaryGene()")
-     val gene : Gene = genes[0]
+    val gene: Gene = genes[0]
 
     /**
      * Return the most important gene defining this parameter.
-     * This is parameter type dependent.
+     * This is parameter-type-dependent.
      * Note that a parameter could have more than 1 gene.
      * For example, a body param could have a gene for the object, and one for its
-     * representation (eg, JSON vs XML)
+     * representation (e.g., JSON vs. XML)
      */
     open fun primaryGene() = genes[0]  //can be overridden if needed
 
-    constructor(name: String, gene : Gene) : this(name, mutableListOf(gene))
+    constructor(name: String, gene: Gene) : this(name, mutableListOf(gene))
 
-    init{
-        if (name.isBlank()){
+    init {
+        if (name.isBlank()) {
             throw IllegalArgumentException("Empty name")
         }
     }
@@ -34,13 +51,14 @@ abstract class Param(
         val copy = super.copy()
         if (copy !is Param)
             throw IllegalStateException("mismatched type: the type should be Param, but it is ${this::class.java.simpleName}")
+        copy.description = description
         return copy as Param
     }
 
 
-    open fun seeGenes() : List<Gene> =  genes
+    open fun seeGenes(): List<Gene> = genes
 
     override fun copyContent(): Param {
         throw IllegalStateException("${this::class.java.simpleName}: copyContent() IS NOT IMPLEMENTED")
     }
-}
+}

core/src/main/kotlin/org/evomaster/core/problem/rest/builder/RestActionBuilderV3.kt

@@ -492,8 +492,10 @@ object RestActionBuilderV3 {
                         null
                     }
                 } ?: listOf()
+
             val action = RestCallAction(actionId, verb, restPath, params, produces = produces,
-                operationId = operation.operationId, links = links)
+                operationId = operation.operationId, links = links
+            )
 
             //TODO update for new parser
 //                        /*This section collects information regarding the types of data that are
@@ -591,6 +593,7 @@ object RestActionBuilderV3 {
                             messages: MutableList<String>
     ) {
         val name = p.name ?: "undefined"
+        val description = p.description
 
         if(p.schema == null){
             messages.add("No schema definition for parameter $name")
@@ -620,17 +623,18 @@ object RestActionBuilderV3 {
             gene = OptionalGene(name, gene)
         }
 
+        // TODO: Adding description to the parameter occurs in multiple places. This can be refactored.
         when (p.`in`) {
-
-            "query" -> {
-                params.add(QueryParam(name, gene, p.explode ?: true, p.style ?: Parameter.StyleEnum.FORM))
-            }
+            "query" -> params.add(QueryParam(name, gene, p.explode ?: true, p.style ?: Parameter.StyleEnum.FORM)
+                    .apply { this.description = description })
             /*
                 a path is inside a Disruptive Gene, because there are cases in which we want to prevent
                 mutation. Note that 1.0 means can always be mutated
              */
-            "path" -> params.add(PathParam(name, CustomMutationRateGene("d_", gene, 1.0)))
-            "header" -> params.add(HeaderParam(name, gene))
+            "path" -> params.add(PathParam(name, CustomMutationRateGene("d_", gene, 1.0))
+                .apply { this.description = description }
+            )
+            "header" -> params.add(HeaderParam(name, gene).apply { this.description = description })
             "cookie" -> params // do nothing?
             //TODO "cookie" does it need any special treatment? as anyway handled in auth configs
             else -> throw IllegalStateException("Unrecognized: ${p.getIn()}")
@@ -706,6 +710,7 @@ object RestActionBuilderV3 {
         }
 
         val name = "body"
+        val description = operation.description ?: null
 
         val bodies = resolvedBody.content?.filter {
             /*
@@ -752,6 +757,8 @@ object RestActionBuilderV3 {
 
         val contentTypeGene = EnumGene<String>("contentType", bodies.keys)
         val bodyParam = BodyParam(gene, contentTypeGene)
+            .apply { this.description = description }
+
         val ns = bodyParam.notSupportedContentTypes
         if(ns.isNotEmpty()){
             messages.add("Not supported content types for body payload in $verb:$restPath : ${ns.joinToString()}")
@@ -810,17 +817,22 @@ object RestActionBuilderV3 {
         if (schema.enum?.isNotEmpty() == true) {
 
             when (type) {
-                "string" ->
+                "string" -> {
                     return EnumGene(name, (schema.enum.map {
                         if (it !is String)
-                            LoggingUtil.uniqueWarn(log, "an item of enum is not string (ie, ${it::class.java.simpleName}) for a property whose `type` is string and `name` is $name")
+                            LoggingUtil.uniqueWarn(
+                                log,
+                                "an item of enum is not string (ie, ${it::class.java.simpleName}) for a property whose `type` is string and `name` is $name"
+                            )
                         it.toString()
                     } as MutableList<String>).apply {
-                        if(options.invalidData) {
+                        if (options.invalidData) {
                             //Besides the defined values, add one to test robustness
                             add("EVOMASTER")
                         }
                     })
+                        .apply { this.description = schema.description }
+                }
                 /*
                     Looks like a possible bug in the parser, where numeric enums can be read as strings... got this
                     issue in GitLab schemas, eg for visibility_level
@@ -1509,6 +1521,11 @@ object RestActionBuilderV3 {
             else -> throw IllegalStateException("cannot create gene with constraints for gene:${geneClass.name}")
         }
 
+        // TODO: Seran: Investigate
+        if (mainGene.description.isNullOrBlank()) {
+            mainGene.description = schema.description
+        }
+
         /*
             See:
             https://swagger.io/docs/specification/adding-examples/
@@ -1668,6 +1685,7 @@ object RestActionBuilderV3 {
             minLength = max(defaultMin, if (options.enableConstraintHandling) schema.minLength ?: 0 else 0),
             invalidChars = if(isInPath) listOf('/','.') else listOf()
         )
+            .apply { this.description = schema.description }
     }
 
     private fun createObjectFromReference(name: String,