Feature: allow to provide multiple examples of responces

[SerVB]

For example, I have the following endpoint:

        delete<ProductIdParam, SuccessResult>(
            info(
                summary = "Remove a product.",
                description = "The product is removed only if a product with the same ID exists. Returns `${SuccessResult::class.simpleName}` saying whether the product has been removed."
            ),
            example = SuccessResult.OK,
            body = { param -> removeProduct(param.id, this::respond) }
        )

I want to specify different examples, for example, with different status codes. So maybe example should be renamed to examples and receive an iterable. Possible usage:

        delete<ProductIdParam, SuccessResult>(
            info(
                summary = "Remove a product.",
                description = "The product is removed only if a product with the same ID exists. Returns `${SuccessResult::class.simpleName}` saying whether the product has been removed."
            ),
            examples = listOf(SuccessResult.OK, SuccessResult.NOT_OK),
            body = { param -> removeProduct(param.id, this::respond) }
        )

The same for other methods (and parameters like exampleResponse).

[SerVB]

The result will be like this:

[Wicpar]

The planned behavior for different responses was to use exception handlers for non 200 codes.

//locally or in the StatusPages plugin globally
throws(APIException.apiException(HttpStatusCode.BadRequest, "example") {ex: CustomException ->
    ex.toString() // transform the exception into the proper response payload.
}) {
// routes
}

There was no example provided for exceptions in the current version, the changes are made on the reworked-model branch, where you can specify one example per response code. (make sure you got jitpack to build the latest snapshot)

Multiple responses on one response code are outside a reasonable workload to add at this point, i will close this issue as there is a solution to your problem even if it is not optimal.