feat: add plugin to support ktor-server-resources (#358)

This commit is contained in:
Serhii Prodan
2022-10-29 14:14:32 +02:00
committed by GitHub
parent e4217843b7
commit 4946a27327
14 changed files with 630 additions and 1 deletions

View File

@ -0,0 +1,60 @@
The Ktor Resources API allows users to define their routes in a type-safe manner.
You can read more about it [here](https://ktor.io/docs/type-safe-routing.html).
Kompendium supports Ktor-Resources through an ancillary module `kompendium-resources`
## Adding the Artifact
Prior to documenting your resources, you will need to add the artifact to your gradle build file.
```kotlin
dependencies {
implementation("io.bkbn:kompendium-resources:$version")
}
```
## Installing Plugin
Once you have installed the dependency, you can install the plugin. The `NotarizedResources` plugin is an _application_ level plugin, and **must** be install after both the `NotarizedApplication` plugin and the Ktor `Resources` plugin.
```kotlin
private fun Application.mainModule() {
install(Resources)
install(NotarizedApplication()) {
spec = baseSpec
}
install(NotarizedResources()) {
resources = mapOf(
Listing::class to NotarizedResources.ResourceMetadata(
parameters = listOf(
Parameter(
name = "name",
`in` = Parameter.Location.path,
schema = TypeDefinition.STRING
),
Parameter(
name = "page",
`in` = Parameter.Location.path,
schema = TypeDefinition.INT
)
),
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 😱")
}
}
),
)
}
}
```
Here, the `resources` property is a map of `KClass<*>` to `ResourceMetadata` instance describing that resource. This metadata is functionally identical to how a standard `NotarizedRoute` is defined.
> ⚠️ If you try to map a class that is not annotated with the ktor `@Resource` annotation, you will get a runtime
> exception!