Is there a way to add a description to the properties?

[LeatherDeerAU]

Hi! I wanted to see something like

data class Person(
  @Desctription("name of person)
  val name: String,
)

[lns-ross]

This is a general swagger question not necessarily relevant to this utility/plugin.

That said, there is a quirk that is Kotlin-specific, the annotation needs to be field scoped.

@Schema
data class Person(
  @field:Schema(description = "name of person")
  var name: String,
)

There may be other ways but this worked for us.

[LeatherDeerAU]

Thanks for the answer! But the annotation did not help, there is still no description of the fields in the swagger. I used io.swagger.core.v3:swagger-annotations:2.2.8. Swagger has all fields of the type specified in body<Type>. It's as if he ignores annotations or doesn't know them.

I looked at the code, when creating an open api schema from a json schema, the "description" field is just not created. I think it's a plugin problem. If there is a way to configure the plugin so that it sees the annotations, please share.

[LeatherDeerAU]

I opened and closed PR. https://github.com/SMILEY4/ktor-swagger-ui/pull/35/files Unnecessary changes.

But even if the json-scheme is with a field description, without this change in toSchemaMethod

node["description"]?.let { this.description = it.asText() }

the description will eventually not be in the swager?

[SMILEY4]

Hi, thanks for the suggestions and discussion.

I created a new version (1.4.0) with (basic) support for the schema-annotation - (almost the same as in your PR). You can now annotate your models like in the following example

@Schema(title = "The Schema for a person")
data class Person(
    @field:Schema(description = "the name of the person")
    val name: String,
    @field:Schema(description = "the age of the person in years", nullable = true)
    val age: Int?
)

[lns-ross]

@SMILEY4 thanks for this. One more field that most folks find crucial would be required. It's needed for fields in both request & response bodies.

Just a thought. :smile:

[SMILEY4]

required should have already worked and didn't require any change. I'll add it to the wiki/changelog though.

[lns-ross]

Perfect! Thx again. :grin: