@ -7,5 +7,5 @@ From there, a `NotarizedRoute` plugin is attached to each route you wish to docu
|
||||
be an iterative process. Each route you notarize will be picked up and injected into the OpenAPI spec that Kompendium
|
||||
generates for you.
|
||||
|
||||
Finally, there is the `NotarizedLocations` plugin that allows you to leverage and document your usage of the
|
||||
Ktor [Locations](https://ktor.io/docs/locations.html) API.
|
||||
Finally, there is the `NotarizedResources` plugin that allows you to leverage and document your usage of the
|
||||
Ktor [Resources](https://ktor.io/docs/server-resources.html) API.
|
||||
|
@ -1,62 +0,0 @@
|
||||
The Ktor Locations API is an experimental API that allows users to add increased type safety to their defined routes.
|
||||
|
||||
You can read more about it [here](https://ktor.io/docs/locations.html).
|
||||
|
||||
Kompendium supports Locations through an ancillary module `kompendium-locations`
|
||||
|
||||
## Adding the Artifact
|
||||
|
||||
Prior to documenting your locations, you will need to add the artifact to your gradle build file.
|
||||
|
||||
```kotlin
|
||||
dependencies {
|
||||
implementation("io.bkbn:kompendium-locations:latest.release")
|
||||
}
|
||||
```
|
||||
|
||||
## Installing Plugin
|
||||
|
||||
Once you have installed the dependency, you can install the plugin. The `NotarizedLocations` plugin is an _application_
|
||||
level plugin, and **must** be install after both the `NotarizedApplication` plugin and the Ktor `Locations` plugin.
|
||||
|
||||
```kotlin
|
||||
private fun Application.mainModule() {
|
||||
install(Locations)
|
||||
install(NotarizedApplication()) {
|
||||
spec = baseSpec
|
||||
}
|
||||
install(NotarizedLocations()) {
|
||||
locations = mapOf(
|
||||
Listing::class to NotarizedLocations.LocationMetadata(
|
||||
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 `locations` property is a map of `KClass<*>` to metadata describing that locations metadata. 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 `@Location` annotation, you will get a runtime
|
||||
> exception!
|
Reference in New Issue
Block a user