V1 Documenting Routes (Responses)

Adding information about the possible responses of a route. See the official OpenAPI Specification for more information.

get("hello", {
    response {
        HttpStatusCode.OK to {
            description = "The operation was successful"
            body {
                //...
            }
            header<String>(HttpHeaders.ContentLength) {
                description = "The length of the returned content"
                required = false
                deprecated = true
            }
        }
        HttpStatusCode.InternalServerError to {
            description = "Something went wrong"
        }
        default {
            description = "Default response"
        }
        "Custom" to {
            description = "Response to custom status-code"
        }
    }
}) {
    // handle request...
}

Maps Http-Status-Codes to Response-Specification-Objects. A status code can only be defined once (though it is possible to provide multiple example bodies for a status code). If the route requires authentication, an optional default response documentation for "401 Unauthorized" is added, if one is specified via defaultUnauthorizedResponse in the plugin configuration.

• description - A short description of the response
• body - the (optional) response body. See Request and Response Bodies for more information.
• header - any amount of header entries.
  • description - a short description of the header
  • required - whether the header is required or optional
  • deprecated - whether the header is deprecated and should no longer be used