V2 Request and Response Bodies Examples

Providing Example-Values

Any number of example-values can be provided for each body. The provided values MUST match (or be a sub-type of) the specified type of the body.

body<Pet>() {
    example("First", Pet(1, "Chloe", "cat")) {
        summary = "A short summary of the example"
        description = "A longer description of the example"
    }
    example("Second", Pet(2, "Oliver", "dog"))
}

body<List<Pet>>() {
    example("Example",  listOf(
        Pet(1, "Chloe", "cat"),
        Pet(2, "Oliver", "dog")
    ))
}

data class Pet(
    val id: Int,
    val name: String,
    val tag: String
)

example(name: String, value: Any) {
    summary = "..."
    description = "..."
}

• name - each example must have a name. The name does not need to be unique among all examples.
• value - the example value as a kotlin/java object
• summary - A short summary of the example
• description - A longer description of the example

Auto-Generated Examples

If no example is provided, swagger will automatically generate an example from the specified schema. These can be customized and enhanced with the help of the @Example or @Schema annotations. Both can be added to fields of the models.

Example using the @Example-Annotations:

import io.github.smiley4.ktorswaggerui.dsl.Example

data class Person(

    @Example("Steve")
    val name: String,

    @Example("42")
    val age: Int,

    @Example("172")
    val size: Float,

    @Example("false")
    val robot: Boolean,
)

Example using the @Schema-Annotation:

import io.swagger.v3.oas.annotations.media.Schema

data class Person(

    @field:Schema(example = "Steve")
    val name: String,

    @field:Schema(example = "42")
    val age: Int,

    @field:Schema(example = "172")
    val size: Float,

    @field:Schema(example = "false")
    val robot: Boolean
)

Customizing json-serialization

See here for more information.