V1 Documenting Routes (Request Parameters)

Adding information about path, query and header request parameters. See the official OpenAPI Specification for more information.

get("image/{name}", {
    request {
        pathParameter<String>("name") {
            description = "The name of the image"
        }
        queryParameter<Color>("color") {
            description = "The color of the image"
            example = Color.GREEN
            required = false
            allowEmptyValue = false
            explode = false
            allowReserved = false
        }
        headerParameter<String>("X-Color") {
            description = "The color of the image"
            deprecated = true
        }
    }
}) {
    // handle request...
}

enum class Color {
    RED, GREEN, BLUE
}

Types

• pathParameter - adds information about a parameter provided in the url. The name should match a template path segment. A schema can be provided as a kotlin-class and specifies the data-type of the parameter (e.g. String, Int, any enum, collections via Array<...> or IntArray, ...)
• queryParameter - adds information about a query parameter
• headerParameter - adds information about a parameter provided in the http-header

Options

• name - the name of the parameter
• description - a description of the parameter
• example - an example value
• required - whether the parameter is mandatory or optional
• deprecated - specifies that a parameter is deprecated and SHOULD be transitioned out of usage
• allowEmptyValue - Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value.
• explode - When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect
• allowReserved - Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included. without percent-encoding. This property only applies to query parameters.

As an alternative to passing the type as a generic type-parameter, all types can be passed as a normal function-parameter:

// as generic type-parameter
pathParameter<String>("name") {...}
// as function-parameter
pathParameter("name", String::class) {...}