Basic Information

The Swagger-UI plugin provides functions to create documented get, post, put, delete, patch, options, head, route and method routes. These work exactly the same as their respective base Ktor-functions, but allow OpenAPI documentation to be added. Functions to create routes provided by the plugin and those from Ktor can be mixed and allow for a gradual enhancement of the api with documentation.

Documentation can be added at any level and documentation of parent and child routes are merged together, with priority given to the deepest route. (Example: the "route" and a nested "get" have a "description" set. When the two documentations are merged, the description of the "get" takes priority).

routing {

    route("api", {
        // possible to add api-documentation here too...
    }) {

        // a documented GET-route
        get("hello", {

            // basic information about the route
            specId = PluginConfigDsl.DEFAULT_SPEC_ID
            operationId = "hello"
            tags = emptySet<String>()
            summary = "Hello-World route"
            description = "A Hello-World route"
            deprecated = false
            hidden = false
            protected = false
            securitySchemeNames = emptySet<String>()
            externalDocs { /*...*/ }
            server("testing") { /*...*/ }

            // information about the request
            request { /*...*/ }

            // information about possible responses
            response { /*...*/ }

        }) {
            // handle the request ...
            call.respondText("Hello ${call.request.queryParameters["name"]}")
        }

    }

}

Property	Description	Default
specId	The id of the openapi-spec this route belongs to. 'Null' to use default spec. See Multiple Api-Specs for more information.	null, is automatically assigned to default spec
tags	A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. These tags will be merged with the tags generated by tags.tagGenerator specified in the plugin configuration.	empty
operationId	A unique string used to identify the operation. The (case-sensitive) id should be unique among all operations described in the API.	null
summary	A short summary of what the operation does.	null
description	A verbose explanation of the operations' behavior.	null
deprecated	Whether this route is deprecated.	false
hidden	Whether to include this route in the openapi-spec.	false
protected	Specifies whether this operation is protected. If not specified (i.e. "null"), the authentication state of the ktor-route will be used (i.e. whether it is surrounded by an authenticate-block or not).	null
securitySchemeNames	The names of the possible security mechanisms specified in the plugin configuration. If not specified, the default names specified in the plugin configuration (security.defaultSecuritySchemeNames) will be used. This field only has an effect for protected routes.	empty
externalDocs	OpenAPI external docs configuration - link and description of an external documentation.	null
externalDocs.url	A URL to the external documentation.	"/"
externalDocs.description	A short description of the external documentation. For more information, see OpenApi-Spec Configuration.	null
server	OpenAPI server configuration - an array of servers, which provide connectivity information to a target server. Multiple servers can be configured by repeating this block.
request	Information about the request.
responses	Possible responses as they are returned from executing this operation.

Request

Information about a request is added in the request-block of a route-documentation.

get("hello", {

    //...

    request {

        pathParameter<String>("paramname") {
            description = "A request parameter"
            example("Example #1") {
                value = "example value"
                summary = "an example"
                description = "An example value for the parameter"
            }
        }
        queryParameter<String>("paramname") { /*...*/ }
        headerParameter<String>("paramname") { /*...*/ }

        body<MyResponse>() {
            description = "The response body"
            required = true
            mediaTypes = setOf(ContentType.Application.Json, ContentType.Application.Xml)
            example("Example #1") {
                value = "example value"
                summary = "an example"
                description = "An example value for the body"
            }
        }

        multipartBody {
            mediaTypes = setOf(ContentType.MultiPart.FormData)
            part<String>("metadata") {
                mediaTypes = setOf(
                    ContentType.Text.Plain
                )
            }
            part<String>("image",) {
                header<Long>("size") {
                    description = "the size of the file in bytes"
                    required = true
                    deprecated = false
                    explode = false
                }
                mediaTypes = setOf(
                    ContentType.Image.PNG,
                    ContentType.Image.JPEG,
                )
            }
        }

    }

}) {
    // handle the request ...
}

Property	Description	Default
pathParameter	A path parameters that is applicable for this operation. The type/schema can be specified in multiple ways. See Types and Schemas for more information.
queryParameter	A query parameters that is applicable for this operation. The type/schema can be specified in multiple ways. See Types and Schemas for more information.
headerParameter	A header parameters that is applicable for this operation. The type/schema can be specified in multiple ways. See Types and Schemas for more information.
*Parameter.description	A short description of the parameter.	null
*Parameter.required	Whether the parameter is mandatory or optional	null
*Parameter.deprecated	Specifies that a parameter is deprecated and should be transitioned out of usage	null
*Parameter.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.	null
*Parameter.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	null
*Parameter.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.	null
*Parameter.style	Describes how the parameter value will be serialized depending on the type of the parameter value.	null
*Parameter.example(examplename)	Multiple example values with different names can be specified for a parameter. Shared examples can be specified as well - see Shared Examples for more information.
*Parameter.example(examplename).value	The example value.	null
*Parameter.example(examplename).summary	A short summary of this example.	null
*Parameter.example(examplename).description	A description of this example.	null
body	Specify information about the request body. See Request and Response Bodies for more information.	null
multipartBody	Specify information about the multipart request body. See Request and Response Bodies for more information.	null

Responses

Adding information about the possible responses of a route.

get("hello", {

    //...

    response {
        HttpStatusCode.OK to {
            description = "The operation was successful"
            header<String>("Content-Length") {
                description = "The length of the returned content"
                required = false
                deprecated = true
            }
            body {
                // See Request ...
            }
            multipartBody {

            }
        }
        HttpStatusCode.InternalServerError to { /*...*/ }
        default { /*...*/ }
        "CustomStatus" to { /*...*/ }
    }
}) {
    // handle the 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.

Parameter	Description	Default
description	A short description of the response	null
header	Headers of a a specific response. Repeat this block to document multiple headers. See Types and Schemas for information on how to specify the type or schema of the header.	empty
body	Specify information about the response body. See Request and Response Bodies for more information.	null
multipartBody	Specify information about the multipart response body. See Request and Response Bodies for more information.	null

Request and Response Bodies

Information about request and response bodies can be added in the respective blocks.

get("hello", {

    //...

    request {

        body<MyResponse>() {
            description = "The response body"
            required = true
            mediaTypes = setOf(ContentType.Application.Json, ContentType.Application.Xml)
            example("Example #1") {
                value = "example value"
                summary = "an example"
                description = "An example value for the body"
            }
        }

        multipartBody {
            mediaTypes = setOf(ContentType.MultiPart.FormData)
            part<String>("metadata") {
                mediaTypes = setOf(
                    ContentType.Text.Plain
                )
            }
            part<String>("image",) {
                header<Long>("size") {
                    description = "the size of the file in bytes"
                    required = true
                    deprecated = false
                    explode = false
                }
                mediaTypes = setOf(
                    ContentType.Image.PNG,
                    ContentType.Image.JPEG,
                )
            }
        }

    }

    response {
        HttpStatusCode.OK to {
            body {
                // ...
            }
            multipartBody {
                // ...
            }
        }
    }
}) {
    // handle the request ...
}

Property	Description	Default
*.body	Specify information about the request/response body. See Types and Schemas for information on how to specify the type or schema.	null
*.body.description	A brief description of the body	null
*.body.required	Whether the body is required or optional	null
*.body.mediaTypes	Bodies 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)	empty, chosen automatically
*.body.example(examplename)	Example values with different names can be specified for a body. Shared examples can be specified as well - see Shared Examples for more information.
*.body.example(examplename).value	The example value.	null
*.body.example(examplename).summary	A short summary of this example.	null
*.body.example(examplename).description	A description of this example.	null
*.multipartBody	Specify information about the multipart request/response body.
*.multipartBody.description	A brief description of the body	null
*.multipartBody.required	Whether the body is required or optional	null
*.multipartBody.mediaTypes	Bodies 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)	empty, chosen automatically
*.multipartBody.part(name)	Specify information about a named part of a multipart-body. Multiple parts can be added by repeating this block. See Types and Schemas for information on how to specify the type or schema of the part.
*.multipartBody.part(name).mediaTypes	Set a specific content types for this part.	empty
*.multipartBody.part(name).header(name)	Headers of a specific part. Repeat this block to document multiple headers. See Types and Schemas for information on how to specify the type or schema of the header.	empty
*.multipartBody.part(name).header(name).description	A description of the header.	null
*.multipartBody.part(name).header(name).required	Determines whether this header is mandatory.	null
*.multipartBody.part(name).header(name).deprecated	Specifies that a header is deprecated and SHOULD be transitioned out of usage.	null
*.multipartBody.part(name).header(name).explode	Specifies whether arrays and objects should generate separate parameters for each array item or object property.	null