feat: add plugin to support ktor-server-resources (#358)
This commit is contained in:
Serhii Prodan
42
resources/build.gradle.kts
Normal file
42
resources/build.gradle.kts
Normal file
@ -0,0 +1,42 @@
|
||||
plugins {
|
||||
kotlin("jvm")
|
||||
kotlin("plugin.serialization")
|
||||
id("io.bkbn.sourdough.library.jvm")
|
||||
id("io.gitlab.arturbosch.detekt")
|
||||
id("com.adarshr.test-logger")
|
||||
id("maven-publish")
|
||||
id("java-library")
|
||||
id("signing")
|
||||
id("org.jetbrains.kotlinx.kover")
|
||||
}
|
||||
|
||||
sourdoughLibrary {
|
||||
libraryName.set("Kompendium Resources")
|
||||
libraryDescription.set("Supplemental library for Kompendium offering support for Ktor's Resources API")
|
||||
}
|
||||
|
||||
dependencies {
|
||||
// Versions
|
||||
val detektVersion: String by project
|
||||
|
||||
// IMPLEMENTATION
|
||||
|
||||
implementation(projects.kompendiumCore)
|
||||
implementation("io.ktor:ktor-server-core:2.1.2")
|
||||
implementation("io.ktor:ktor-server-resources:2.1.2")
|
||||
|
||||
// TESTING
|
||||
|
||||
testImplementation(testFixtures(projects.kompendiumCore))
|
||||
|
||||
// Formatting
|
||||
detektPlugins("io.gitlab.arturbosch.detekt:detekt-formatting:$detektVersion")
|
||||
}
|
||||
|
||||
testing {
|
||||
suites {
|
||||
named("test", JvmTestSuite::class) {
|
||||
useJUnitJupiter()
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,78 @@
|
||||
package io.bkbn.kompendium.resources
|
||||
|
||||
import io.bkbn.kompendium.core.attribute.KompendiumAttributes
|
||||
import io.bkbn.kompendium.core.metadata.DeleteInfo
|
||||
import io.bkbn.kompendium.core.metadata.GetInfo
|
||||
import io.bkbn.kompendium.core.metadata.HeadInfo
|
||||
import io.bkbn.kompendium.core.metadata.OptionsInfo
|
||||
import io.bkbn.kompendium.core.metadata.PatchInfo
|
||||
import io.bkbn.kompendium.core.metadata.PostInfo
|
||||
import io.bkbn.kompendium.core.metadata.PutInfo
|
||||
import io.bkbn.kompendium.core.util.Helpers.addToSpec
|
||||
import io.bkbn.kompendium.core.util.SpecConfig
|
||||
import io.bkbn.kompendium.oas.path.Path
|
||||
import io.bkbn.kompendium.oas.payload.Parameter
|
||||
import io.ktor.resources.Resource
|
||||
import io.ktor.server.application.createApplicationPlugin
|
||||
import kotlin.reflect.KClass
|
||||
import kotlin.reflect.full.findAnnotation
|
||||
import kotlin.reflect.full.hasAnnotation
|
||||
import kotlin.reflect.full.memberProperties
|
||||
|
||||
object NotarizedResources {
|
||||
|
||||
data class ResourceMetadata(
|
||||
override var tags: Set<String> = emptySet(),
|
||||
override var parameters: List<Parameter> = emptyList(),
|
||||
override var get: GetInfo? = null,
|
||||
override var post: PostInfo? = null,
|
||||
override var put: PutInfo? = null,
|
||||
override var delete: DeleteInfo? = null,
|
||||
override var patch: PatchInfo? = null,
|
||||
override var head: HeadInfo? = null,
|
||||
override var options: OptionsInfo? = null,
|
||||
override var security: Map<String, List<String>>? = null,
|
||||
) : SpecConfig
|
||||
|
||||
class Config {
|
||||
lateinit var resources: Map<KClass<*>, ResourceMetadata>
|
||||
}
|
||||
|
||||
operator fun invoke() = createApplicationPlugin(
|
||||
name = "NotarizedResources",
|
||||
createConfiguration = NotarizedResources::Config
|
||||
) {
|
||||
val spec = application.attributes[KompendiumAttributes.openApiSpec]
|
||||
val serializableReader = application.attributes[KompendiumAttributes.schemaConfigurator]
|
||||
pluginConfig.resources.forEach { (k, v) ->
|
||||
val path = Path()
|
||||
path.parameters = v.parameters
|
||||
v.get?.addToSpec(path, spec, v, serializableReader)
|
||||
v.delete?.addToSpec(path, spec, v, serializableReader)
|
||||
v.head?.addToSpec(path, spec, v, serializableReader)
|
||||
v.options?.addToSpec(path, spec, v, serializableReader)
|
||||
v.post?.addToSpec(path, spec, v, serializableReader)
|
||||
v.put?.addToSpec(path, spec, v, serializableReader)
|
||||
v.patch?.addToSpec(path, spec, v, serializableReader)
|
||||
|
||||
val resource = k.getResourcesFromClass()
|
||||
spec.paths[resource] = path
|
||||
}
|
||||
}
|
||||
|
||||
private fun KClass<*>.getResourcesFromClass(): String {
|
||||
// todo if parent
|
||||
|
||||
val resource = findAnnotation<Resource>()
|
||||
?: error("Cannot notarize a resource without annotating with @Resource")
|
||||
|
||||
val path = resource.path
|
||||
val parent = memberProperties.map { it.returnType.classifier as KClass<*> }.find { it.hasAnnotation<Resource>() }
|
||||
|
||||
return if (parent == null) {
|
||||
path
|
||||
} else {
|
||||
parent.getResourcesFromClass() + path
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,120 @@
|
||||
package io.bkbn.kompendium.resources
|
||||
|
||||
import Listing
|
||||
import Type
|
||||
import io.bkbn.kompendium.core.fixtures.TestHelpers.openApiTestAllSerializers
|
||||
import io.bkbn.kompendium.core.fixtures.TestResponse
|
||||
import io.bkbn.kompendium.core.metadata.GetInfo
|
||||
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
|
||||
import io.bkbn.kompendium.oas.payload.Parameter
|
||||
import io.kotest.core.spec.style.DescribeSpec
|
||||
import io.ktor.http.HttpStatusCode
|
||||
import io.ktor.server.application.call
|
||||
import io.ktor.server.application.install
|
||||
import io.ktor.server.resources.Resources
|
||||
import io.ktor.server.resources.get
|
||||
import io.ktor.server.response.respondText
|
||||
|
||||
class KompendiumResourcesTest : DescribeSpec({
|
||||
describe("Resource Tests") {
|
||||
it("Can notarize a simple resource") {
|
||||
openApiTestAllSerializers(
|
||||
snapshotName = "T0001__simple_resource.json",
|
||||
applicationSetup = {
|
||||
install(Resources)
|
||||
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("Resource")
|
||||
description("example resource")
|
||||
response {
|
||||
responseCode(HttpStatusCode.OK)
|
||||
responseType<TestResponse>()
|
||||
description("does great things")
|
||||
}
|
||||
}
|
||||
),
|
||||
)
|
||||
}
|
||||
}
|
||||
) {
|
||||
get<Listing> { listing ->
|
||||
call.respondText("Listing ${listing.name}, page ${listing.page}")
|
||||
}
|
||||
}
|
||||
}
|
||||
it("Can notarize nested resources") {
|
||||
openApiTestAllSerializers(
|
||||
snapshotName = "T0002__nested_resources.json",
|
||||
applicationSetup = {
|
||||
install(Resources)
|
||||
install(NotarizedResources()) {
|
||||
resources = mapOf(
|
||||
Type.Edit::class to NotarizedResources.ResourceMetadata(
|
||||
parameters = listOf(
|
||||
Parameter(
|
||||
name = "name",
|
||||
`in` = Parameter.Location.path,
|
||||
schema = TypeDefinition.STRING
|
||||
)
|
||||
),
|
||||
get = GetInfo.builder {
|
||||
summary("Edit")
|
||||
description("example resource")
|
||||
response {
|
||||
responseCode(HttpStatusCode.OK)
|
||||
responseType<TestResponse>()
|
||||
description("does great things")
|
||||
}
|
||||
}
|
||||
),
|
||||
Type.Other::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("Other")
|
||||
description("example resource")
|
||||
response {
|
||||
responseCode(HttpStatusCode.OK)
|
||||
responseType<TestResponse>()
|
||||
description("does great things")
|
||||
}
|
||||
}
|
||||
),
|
||||
)
|
||||
}
|
||||
}
|
||||
) {
|
||||
get<Type.Edit> { edit ->
|
||||
call.respondText("Listing ${edit.parent.name}")
|
||||
}
|
||||
get<Type.Other> { other ->
|
||||
call.respondText("Listing ${other.parent.name}, page ${other.page}")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
@ -0,0 +1,17 @@
|
||||
import io.ktor.resources.Resource
|
||||
import kotlinx.serialization.Serializable
|
||||
|
||||
@Serializable
|
||||
@Resource("/list/{name}/page/{page}")
|
||||
data class Listing(val name: String, val page: Int)
|
||||
|
||||
@Serializable
|
||||
@Resource("/type/{name}")
|
||||
data class Type(val name: String) {
|
||||
@Serializable
|
||||
@Resource("/edit")
|
||||
data class Edit(val parent: Type)
|
||||
@Serializable
|
||||
@Resource("/other/{page}")
|
||||
data class Other(val parent: Type, val page: Int)
|
||||
}
|
||||
92
resources/src/test/resources/T0001__simple_resource.json
Normal file
92
resources/src/test/resources/T0001__simple_resource.json
Normal file
@ -0,0 +1,92 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
|
||||
"info": {
|
||||
"title": "Test API",
|
||||
"version": "1.33.7",
|
||||
"description": "An amazing, fully-ish 😉 generated API spec",
|
||||
"termsOfService": "https://example.com",
|
||||
"contact": {
|
||||
"name": "Homer Simpson",
|
||||
"url": "https://gph.is/1NPUDiM",
|
||||
"email": "chunkylover53@aol.com"
|
||||
},
|
||||
"license": {
|
||||
"name": "MIT",
|
||||
"url": "https://github.com/bkbnio/kompendium/blob/main/LICENSE"
|
||||
}
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": "https://myawesomeapi.com",
|
||||
"description": "Production instance of my API"
|
||||
},
|
||||
{
|
||||
"url": "https://staging.myawesomeapi.com",
|
||||
"description": "Where the fun stuff happens"
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/list/{name}/page/{page}": {
|
||||
"get": {
|
||||
"tags": [],
|
||||
"summary": "Resource",
|
||||
"description": "example resource",
|
||||
"parameters": [],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "does great things",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/TestResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"deprecated": false
|
||||
},
|
||||
"parameters": [
|
||||
{
|
||||
"name": "name",
|
||||
"in": "path",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
},
|
||||
"required": true,
|
||||
"deprecated": false
|
||||
},
|
||||
{
|
||||
"name": "page",
|
||||
"in": "path",
|
||||
"schema": {
|
||||
"type": "number",
|
||||
"format": "int32"
|
||||
},
|
||||
"required": true,
|
||||
"deprecated": false
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"webhooks": {},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"TestResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"c": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"c"
|
||||
]
|
||||
}
|
||||
},
|
||||
"securitySchemes": {}
|
||||
},
|
||||
"security": [],
|
||||
"tags": []
|
||||
}
|
||||
124
resources/src/test/resources/T0002__nested_resources.json
Normal file
124
resources/src/test/resources/T0002__nested_resources.json
Normal file
@ -0,0 +1,124 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
|
||||
"info": {
|
||||
"title": "Test API",
|
||||
"version": "1.33.7",
|
||||
"description": "An amazing, fully-ish 😉 generated API spec",
|
||||
"termsOfService": "https://example.com",
|
||||
"contact": {
|
||||
"name": "Homer Simpson",
|
||||
"url": "https://gph.is/1NPUDiM",
|
||||
"email": "chunkylover53@aol.com"
|
||||
},
|
||||
"license": {
|
||||
"name": "MIT",
|
||||
"url": "https://github.com/bkbnio/kompendium/blob/main/LICENSE"
|
||||
}
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": "https://myawesomeapi.com",
|
||||
"description": "Production instance of my API"
|
||||
},
|
||||
{
|
||||
"url": "https://staging.myawesomeapi.com",
|
||||
"description": "Where the fun stuff happens"
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/type/{name}/edit": {
|
||||
"get": {
|
||||
"tags": [],
|
||||
"summary": "Edit",
|
||||
"description": "example resource",
|
||||
"parameters": [],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "does great things",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/TestResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"deprecated": false
|
||||
},
|
||||
"parameters": [
|
||||
{
|
||||
"name": "name",
|
||||
"in": "path",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
},
|
||||
"required": true,
|
||||
"deprecated": false
|
||||
}
|
||||
]
|
||||
},
|
||||
"/type/{name}/other/{page}": {
|
||||
"get": {
|
||||
"tags": [],
|
||||
"summary": "Other",
|
||||
"description": "example resource",
|
||||
"parameters": [],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "does great things",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/TestResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"deprecated": false
|
||||
},
|
||||
"parameters": [
|
||||
{
|
||||
"name": "name",
|
||||
"in": "path",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
},
|
||||
"required": true,
|
||||
"deprecated": false
|
||||
},
|
||||
{
|
||||
"name": "page",
|
||||
"in": "path",
|
||||
"schema": {
|
||||
"type": "number",
|
||||
"format": "int32"
|
||||
},
|
||||
"required": true,
|
||||
"deprecated": false
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"webhooks": {},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"TestResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"c": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"c"
|
||||
]
|
||||
}
|
||||
},
|
||||
"securitySchemes": {}
|
||||
},
|
||||
"security": [],
|
||||
"tags": []
|
||||
}
|
||||
Reference in New Issue
Block a user