The NotarizedRoute
plugin is the method by which you define the functionality and metadata for an individual route of
your API.
OpenAPI uses the concept of tags in order to logically group operations. Tags defined at the NotarizedRoute
level will
be applied to all operations defined in this route. In order to define tags for a specific operation,
see below.
private fun Route.documentation() {
install(NotarizedRoute()) {
tags = setOf("User")
// will apply the User tag to all operations defined below
}
}
Parameters can be defined at the route level. Doing so will assign the parameters to all operations defined in this route. In order to define parameters for a specific operation, see below.
private fun Route.documentation() {
install(NotarizedRoute()) {
parameters = listOf(
Parameter(
name = "id",
`in` = Parameter.Location.path,
schema = TypeDefinition.STRING
)
)
// Will apply the id parameter to all operations defined below
}
}
Obviously, our route documentation would not be very useful without a way to detail the operations that are available at the specified route. These operations will take the metadata defined, along with any existing info present at the route level detailed above. Together, this defines an OpenAPI path operation.
Each HTTP Operation (Get, Put Post, Patch, Delete, Head, Options) has its own Builder
that Kompendium uses to define
the necessary information to associate with the detailed operation. For example, a simple GET
request could be
defined as follows.
install(NotarizedRoute()) {
get = GetInfo.builder {
summary("Get ImportantDetail")
description("Retrieves an Important Detail from the database")
response {
responseCode(HttpStatusCode.OK)
responseType<TestResponse>()
description("The Detail in Question")
}
}
}
Operation tags work much like route tags, except they only apply to the operation they are defined in. They are defined slightly differently, as a function on the builder, rather than an instance variable directly.
install(NotarizedRoute()) {
get = GetInfo.builder {
tags("User")
// ...
}
}
Operation parameters work much like route parameters, except they only apply to the operation they are defined in. They are defined slightly differently, as a function on the builder, rather than an instance variable directly.
install(NotarizedRoute()) {
get = GetInfo.builder {
parameters(
Parameter(
name = "a",
`in` = Parameter.Location.path,
schema = TypeDefinition.STRING,
),
Parameter(
name = "aa",
`in` = Parameter.Location.query,
schema = TypeDefinition.INT
)
)
// ...
}
}
All operations are required to define a response info block, detailing the standard response that users of the API should expect when performing this operation. At its most simple, doing so looks like the following
get = GetInfo.builder {
summary("Get user by id")
description("A very neat endpoint!")
response {
responseCode(HttpStatusCode.OK)
responseType<ExampleResponse>()
description("Will return whether or not the user is real 😱")
}
}
As you can see, we attach an http status code, a description, and finally the type that represents the payload that
users should expect. In order to indicate that no payload is expected, use responseType<Unit>()
. This should typically
be paired with a 204
status code.
On operations that allow a request body to be associated, you must also define a response info block so that Kompendium can determine how to populate the required operation data.
post = PostInfo.builder {
summary("Create User")
description("Will create a new user entity")
request {
requestType<CreateUserRequest>()
description("Data required to create new user")
}
response {
responseCode(HttpStatusCode.Created)
responseType<UserCreatedResponse>()
description("User was created successfully")
}
}
In addition to the standard response, you can attach additional responses via the canRespond
function.
get = GetInfo.builder {
summary("Get user by id")
description("A very neat endpoint!")
response {
responseCode(HttpStatusCode.OK)
responseType<ExampleResponse>()
description("Will return whether or not the user is real 😱")
}
canRespond {
description("Bad Things Happened")
responseCode(HttpStatusCode.InternalServerError)
responseType<ExceptionResponse>()
}
}
By default, Kompendium will set the only media type to "application/json". If you would like to override the media type
for a specific request or response (including errors), you can do so with the mediaTypes
method
get = GetInfo.builder {
summary("Get user by id")
description("A very neat endpoint!")
response {
mediaTypes("application/xml")
responseCode(HttpStatusCode.OK)
responseType<ExampleResponse>()
description("Will return whether or not the user is real 😱")
}
}