V2 Request and Response Bodies Basics

body<String>() {
    description = "A brief description of the request body"
    required = true
    example("First", /*value*/) {
        summary = "A short summary of the example"
        description = "A longer description of the example"
    }
    example("Second", /*value*/)
    mediaType(ContentType.Application.Json)
}

• description - A brief description of the body
• required - whether the body is required or optional
• example - specifies a single example for the body. Any amount of examples can be added to a body. See Examples for more information.
• mediaType - the media-type of the object (application/json or text/plain by default)

Schema

Any primitive or more complex Kotlin-class can be used as the schema of a body. If no media-type is specified, a matching one will be picked automatically. The media type for primitive types is always text/plain and application/json for complex types.

body<Int>()
body<Person>()
body<List<Person>>()

data class Person(
    val name: String,
    val age: Int
)

Types can alternatively also be provided as a normal function-parameter, tough this method has some limitations, especially when it comes to generic-types.

body(Int::class)
body(Pet::class)

For file-uploads or downloads java.io.File can be used as the type of the body.

Swagger @Schema-Annotation

Classes and fields can be annotated with the @Schema and @ArraySchema annotations to add information such as an description, example-values, a title for the schema or whether a field is nullable. This only works when the default schema-encoder is used and not overwritten in the encoding-config-section.

The tested and fully supported features of the @Schema-annotation are: title, description, nullable, format, example, minLength, maxLength, minimum, maximum, minItems, maxItems, uniqueItems.

Example:

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

For more information, see https://github.com/victools/jsonschema-generator/tree/main/jsonschema-module-swagger-2 or https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#schema

Media Types

A request/response body can have any amount of supported media types. If no media type is specified and a schema exists, a media type will automatically be chosen (usually "application/json" for complex models and arrays and "text/plain" for everything else)

body<Pet>() {
    mediaType(ContentType.Application.Json)
    mediaType(ContentType.Application.Xml)
}

body {
    mediaType(ContentType.Image.PNG)
    mediaType(ContentType.Image.JPEG)
    mediaType(ContentType.Image.SVG)
}

Multipart-Bodies

The definition for multipart-bodies is similar to that of normal bodies.

multipartBody {
    description = "A brief description of the request body"
    required = true
    mediaType(ContentType.MultiPart.FormData)
    part<File>("myImage") {
        mediaTypes = setOf(
            ContentType.Image.PNG,
            ContentType.Image.JPEG,
            ContentType.Image.GIF
        )
    }
    part<Metadata>("myMetadata")
}
//...
data class Metadata(
    val format: String,
    val location: Coords
)
data class Coords(
    val lat: Float,
    val long: Float
)

• description - A brief description of the multipart-body
• required - whether the multipart-body is required or optional
• mediaType - the media-type of the object (multipart/formdata by default)
• part - one part of the body with the given name and type/schema (use java.io.File for file-uploads/downloads)
  • mediaTypes - specify custom valid content-types for the part
  • headers - include custom headers for the part

OneOf, MultipleOf, TypeOf

The basic schema of a body can easily be enhanced with oneOf, multipleOf (and typeOf).

request {
    // describe a body allowing a mixed list of rectangles, circles and points
    body(
        multipleOf(
            oneOf(
                typeOf(Rectangle::class),
                typeOf(Circle::class),
                typeOf(Point::class),
            )
        )
    )
}

This will result in the following schema:

{
  "type" : "array",
  "items" : {
    "oneOf" : [
      { "$ref" : "#/components/schemas/Rectangle" },
      { "$ref" : "#/components/schemas/Circle" },
      { "$ref" : "#/components/schemas/Point" }
    ]
  }
}

Customizing Schema-Generation

See here for more information.