Compare commits

...

12 Commits

Author SHA1 Message Date
3d27d30a31 feat: support no request body for post, put and patch (#427) 2023-03-15 12:39:35 +00:00
8cc229667e chore: prep for 3.12.0 release 2023-03-14 16:52:16 -04:00
54d12de67a feat: reintroduce swagger compatability (#426) 2023-03-14 20:43:06 +00:00
9b93c887a2 chore(deps): update plugin io.github.gradle-nexus.publish-plugin to v1.2.0 (#424)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-22 06:04:16 +00:00
19d828956b fix(deps): update dependency org.apache.logging.log4j:log4j-core to v2.20.0 (#423)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-21 18:05:45 +00:00
eabe90acfc fix(deps): update dependency org.apache.logging.log4j:log4j-api to v2.20.0 (#422)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-21 17:58:41 +00:00
7c2a2a9c9d fix(deps): update dependency com.google.protobuf:protobuf-java to v3.22.0 (#421)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-17 05:27:43 +00:00
15cdfb229d fix(deps): update kotestversion to v5.5.5 (#420)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-05 21:56:57 +00:00
5a40f37f81 fix(deps): update dependency org.jetbrains.kotlin:kotlin-reflect to v1.8.10 (#418)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-03 05:51:57 +00:00
64f2516f19 chore(deps): update plugin org.jetbrains.kotlin.plugin.serialization to v1.8.10 (#416)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-03 00:22:16 +00:00
2e5e39d3b2 chore(deps): update plugin org.jetbrains.kotlin.jvm to v1.8.10 (#415)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-02 19:52:53 +00:00
5342cf00d1 fix(deps): update ktor to v2.2.3 (#414)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2023-02-01 04:08:51 +00:00
29 changed files with 260 additions and 39 deletions

View File

@ -12,6 +12,18 @@
## Released
## [3.13.0] - March 15th, 2023
### Changed
- Post, Put, and Patch now support not providing request info
## [3.12.0] - March 14th, 2023
### Added
- Add support for swagger documentation
## [3.11.0] - January 5th, 2023
### Added

View File

@ -1,12 +1,12 @@
plugins {
kotlin("jvm") version "1.8.0" apply false
kotlin("plugin.serialization") version "1.8.0" apply false
kotlin("jvm") version "1.8.10" apply false
kotlin("plugin.serialization") version "1.8.10" apply false
id("io.bkbn.sourdough.library.jvm") version "0.12.0" apply false
id("io.bkbn.sourdough.application.jvm") version "0.12.0" apply false
id("io.bkbn.sourdough.root") version "0.12.0"
id("com.github.jakemarsden.git-hooks") version "0.0.2"
id("org.jetbrains.kotlinx.kover") version "0.6.1"
id("io.github.gradle-nexus.publish-plugin") version "1.1.0"
id("io.github.gradle-nexus.publish-plugin") version "1.2.0"
}
gitHooks {

View File

@ -1,7 +1,7 @@
package io.bkbn.kompendium.core.metadata
sealed interface MethodInfoWithRequest : MethodInfo {
val request: RequestInfo
val request: RequestInfo?
abstract class Builder<T : MethodInfoWithRequest> : MethodInfo.Builder<T>() {
internal var request: RequestInfo? = null

View File

@ -4,7 +4,7 @@ import io.bkbn.kompendium.oas.common.ExternalDocumentation
import io.bkbn.kompendium.oas.payload.Parameter
class PatchInfo private constructor(
override val request: RequestInfo,
override val request: RequestInfo?,
override val errors: MutableList<ResponseInfo>,
override val response: ResponseInfo,
override val tags: Set<String>,
@ -26,7 +26,7 @@ class PatchInfo private constructor(
class Builder : MethodInfoWithRequest.Builder<PatchInfo>() {
override fun build() = PatchInfo(
request = request ?: error("request info must be present"),
request = request,
errors = errors,
response = response ?: error("response info must be present"),
tags = tags,

View File

@ -4,7 +4,7 @@ import io.bkbn.kompendium.oas.common.ExternalDocumentation
import io.bkbn.kompendium.oas.payload.Parameter
class PostInfo private constructor(
override val request: RequestInfo,
override val request: RequestInfo?,
override val errors: MutableList<ResponseInfo>,
override val response: ResponseInfo,
override val tags: Set<String>,
@ -26,7 +26,7 @@ class PostInfo private constructor(
class Builder : MethodInfoWithRequest.Builder<PostInfo>() {
override fun build() = PostInfo(
request = request ?: error("request info must be present"),
request = request,
errors = errors,
response = response ?: error("response info must be present"),
tags = tags,

View File

@ -4,7 +4,7 @@ import io.bkbn.kompendium.oas.common.ExternalDocumentation
import io.bkbn.kompendium.oas.payload.Parameter
class PutInfo private constructor(
override val request: RequestInfo,
override val request: RequestInfo?,
override val errors: MutableList<ResponseInfo>,
override val response: ResponseInfo,
override val tags: Set<String>,
@ -26,7 +26,7 @@ class PutInfo private constructor(
class Builder : MethodInfoWithRequest.Builder<PutInfo>() {
override fun build() = PutInfo(
request = request ?: error("request info must be present"),
request = request,
errors = errors,
response = response ?: error("response info must be present"),
tags = tags,

View File

@ -18,7 +18,7 @@ import kotlinx.html.unsafe
/**
* Provides an out-of-the-box route to view docs using ReDoc on the specified [path].
* @param pageTitle Webpage title you wish to be displayed on your docs
* @param route path to docs resource
* @param path path to docs resource
* @param specUrl url to point ReDoc to the OpenAPI json document
*/
fun Route.redoc(pageTitle: String = "Docs", path: String = "/docs", specUrl: String = "/openapi.json") {

View File

@ -0,0 +1,91 @@
package io.bkbn.kompendium.core.routes
import io.ktor.server.application.call
import io.ktor.server.html.respondHtml
import io.ktor.server.routing.Route
import io.ktor.server.routing.get
import io.ktor.server.routing.route
import kotlinx.html.body
import kotlinx.html.div
import kotlinx.html.head
import kotlinx.html.id
import kotlinx.html.link
import kotlinx.html.meta
import kotlinx.html.script
import kotlinx.html.title
import kotlinx.html.unsafe
/**
* Provides an out-of-the-box route to view docs using Swagger
* @see <a href="https://swagger.io/specification/">Swagger OpenApi Specification</a>
* for the latest supported open api version.
* @param pageTitle Webpage title you wish to be displayed on your docs
* @param path path to docs resource
* @param specUrl url to point Swagger to the OpenAPI json document
* @param swaggerVersion version of swagger-ui distribution
*/
fun Route.swagger(
pageTitle: String = "Docs",
path: String = "/swagger-ui",
specUrl: String = "/openapi.json",
swaggerVersion: String? = null
) {
val swaggerVersionSuffix = if (swaggerVersion == null) "" else "@$swaggerVersion"
route(path) {
get {
call.respondHtml {
head {
title {
+pageTitle
}
meta {
charset = "utf-8"
}
meta {
name = "viewport"
content = "width=device-width, initial-scale=1"
}
link {
href = "https://unpkg.com/swagger-ui-dist$swaggerVersionSuffix/swagger-ui.css"
rel = "stylesheet"
}
}
body {
div {
id = "swagger-ui"
}
script {
src = "https://unpkg.com/swagger-ui-dist$swaggerVersionSuffix/swagger-ui-standalone-preset.js"
}
script {
src = "https://unpkg.com/swagger-ui-dist$swaggerVersionSuffix/swagger-ui-bundle.js"
}
unsafe {
+"""
<script>
window.onload = function () {
// Build a system
const ui = SwaggerUIBundle({
url: "$specUrl",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout",
})
window.ui = ui
}
</script>
""".trimIndent()
}
}
}
}
}
}

View File

@ -72,13 +72,15 @@ object Helpers {
when (this) {
is MethodInfoWithRequest -> {
this.request?.let { reqInfo ->
SchemaGenerator.fromTypeOrUnit(
type = this.request.requestType,
type = reqInfo.requestType,
cache = spec.components.schemas,
schemaConfigurator = schemaConfigurator,
enrichment = this.request.typeEnrichment,
enrichment = reqInfo.typeEnrichment,
)?.let { schema ->
spec.components.schemas[this.request.requestType.getSlug(this.request.typeEnrichment)] = schema
spec.components.schemas[reqInfo.requestType.getSlug(reqInfo.typeEnrichment)] = schema
}
}
}
@ -121,15 +123,17 @@ object Helpers {
?.map { listOf(it).toMap() }
?.toMutableList(),
requestBody = when (this) {
is MethodInfoWithRequest -> Request(
description = this.request.description,
content = this.request.requestType.toReferenceContent(
examples = this.request.examples,
mediaTypes = this.request.mediaTypes,
enrichment = this.request.typeEnrichment
is MethodInfoWithRequest -> this.request?.let { reqInfo ->
Request(
description = reqInfo.description,
content = reqInfo.requestType.toReferenceContent(
examples = reqInfo.examples,
mediaTypes = reqInfo.mediaTypes,
enrichment = reqInfo.typeEnrichment
),
required = true
)
}
else -> null
},

View File

@ -48,6 +48,7 @@ import io.bkbn.kompendium.core.util.polymorphicCollectionResponse
import io.bkbn.kompendium.core.util.polymorphicException
import io.bkbn.kompendium.core.util.polymorphicMapResponse
import io.bkbn.kompendium.core.util.polymorphicResponse
import io.bkbn.kompendium.core.util.postNoReqBody
import io.bkbn.kompendium.core.util.primitives
import io.bkbn.kompendium.core.util.reqRespExamples
import io.bkbn.kompendium.core.util.requiredParams
@ -129,6 +130,9 @@ class KompendiumTest : DescribeSpec({
it("Can override media types") {
openApiTestAllSerializers("T0052__override_media_types.json") { overrideMediaTypes() }
}
it("Can support a post request with no request body") {
openApiTestAllSerializers("T0065__post_no_req_body.json") { postNoReqBody() }
}
}
describe("Route Parsing") {
it("Can parse a simple path and store it under the expected route") {

View File

@ -299,3 +299,19 @@ fun Routing.overrideMediaTypes() {
}
}
}
fun Routing.postNoReqBody() {
route("/no_req_body") {
install(NotarizedRoute()) {
post = PostInfo.builder {
summary(defaultPathSummary)
description(defaultPathDescription)
response {
responseType<TestResponse>()
description("Cool response")
responseCode(HttpStatusCode.Created)
}
}
}
}
}

View File

@ -0,0 +1,72 @@
{
"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": {
"/no_req_body": {
"post": {
"tags": [],
"summary": "Great Summary!",
"description": "testing more",
"parameters": [],
"responses": {
"201": {
"description": "Cool response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TestResponse"
}
}
}
}
},
"deprecated": false
},
"parameters": []
}
},
"webhooks": {},
"components": {
"schemas": {
"TestResponse": {
"type": "object",
"properties": {
"c": {
"type": "string"
}
},
"required": [
"c"
]
}
},
"securitySchemes": {}
},
"security": [],
"tags": []
}

View File

@ -5,6 +5,7 @@ import com.fasterxml.jackson.databind.SerializationFeature
import io.bkbn.kompendium.core.fixtures.TestSpecs.defaultSpec
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.KotlinXSchemaConfigurator
import io.bkbn.kompendium.json.schema.definition.JsonSchema
import io.bkbn.kompendium.oas.OpenApiSpec
@ -130,6 +131,7 @@ object TestHelpers {
}
application(applicationSetup)
routing {
swagger()
redoc()
routeUnderTest()
}

View File

@ -1,5 +1,5 @@
# Kompendium
project.version=3.11.1
project.version=3.13.0
# Kotlin
kotlin.code.style=official
# Gradle
@ -9,6 +9,6 @@ org.gradle.jvmargs=-Xmx2000m
org.gradle.parallel=true
# Dependencies
ktorVersion=2.2.2
kotestVersion=5.5.4
ktorVersion=2.2.3
kotestVersion=5.5.5
detektVersion=1.21.0

View File

@ -23,7 +23,7 @@ dependencies {
// Kompendium
api(projects.kompendiumEnrichment)
implementation("org.jetbrains.kotlin:kotlin-reflect:1.8.0")
implementation("org.jetbrains.kotlin:kotlin-reflect:1.8.10")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.4.1")
// Formatting

View File

@ -22,8 +22,8 @@ dependencies {
// IMPLEMENTATION
implementation(projects.kompendiumCore)
implementation("io.ktor:ktor-server-core:2.2.2")
implementation("io.ktor:ktor-server-locations:2.2.2")
implementation("io.ktor:ktor-server-core:2.2.3")
implementation("io.ktor:ktor-server-locations:2.2.3")
// TESTING

View File

@ -35,8 +35,8 @@ dependencies {
// Logging
implementation("org.apache.logging.log4j:log4j-api-kotlin:1.2.0")
implementation("org.apache.logging.log4j:log4j-api:2.19.0")
implementation("org.apache.logging.log4j:log4j-core:2.19.0")
implementation("org.apache.logging.log4j:log4j-api:2.20.0")
implementation("org.apache.logging.log4j:log4j-core:2.20.0")
implementation("org.slf4j:slf4j-api:2.0.6")
implementation("org.slf4j:slf4j-simple:2.0.6")

View File

@ -4,6 +4,7 @@ import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.plugin.NotarizedRoute
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.oas.component.Components
import io.bkbn.kompendium.oas.payload.Parameter
@ -68,6 +69,7 @@ private fun Application.mainModule() {
)
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
authenticate("basic") {
route("/{id}") {

View File

@ -4,6 +4,7 @@ import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.plugin.NotarizedRoute
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.KotlinXSchemaConfigurator
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.oas.payload.Parameter
@ -49,6 +50,7 @@ private fun Application.mainModule() {
schemaConfigurator = KotlinXSchemaConfigurator()
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
route("/{id}") {
idDocumentation()

View File

@ -4,6 +4,7 @@ import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.plugin.NotarizedRoute
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.oas.payload.Parameter
import io.bkbn.kompendium.oas.serialization.KompendiumSerializersModule
@ -51,6 +52,7 @@ private fun Application.mainModule() {
)
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
route("/{id}") {

View File

@ -5,6 +5,7 @@ import io.bkbn.kompendium.core.metadata.PostInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.plugin.NotarizedRoute
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.enrichment.TypeEnrichment
import io.bkbn.kompendium.json.schema.KotlinXSchemaConfigurator
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
@ -50,6 +51,7 @@ private fun Application.mainModule() {
schemaConfigurator = KotlinXSchemaConfigurator()
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
enrichedDocumentation()
post {

View File

@ -4,6 +4,7 @@ import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.plugin.NotarizedRoute
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.oas.payload.Parameter
import io.bkbn.kompendium.oas.serialization.KompendiumSerializersModule
@ -50,6 +51,7 @@ private fun Application.mainModule() {
}
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
route("/{id}") {

View File

@ -6,6 +6,7 @@ import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.plugin.NotarizedRoute
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.SchemaConfigurator
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.oas.payload.Parameter
@ -48,6 +49,7 @@ private fun Application.mainModule() {
schemaConfigurator = GsonSchemaConfigurator()
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
route("/{id}") {

View File

@ -5,6 +5,7 @@ import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.plugin.NotarizedRoute
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.oas.component.Components
import io.bkbn.kompendium.oas.payload.Parameter
@ -80,6 +81,7 @@ private fun Application.mainModule() {
}
routing {
authenticate("basic") {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
route("/{id}") {
locationDocumentation()

View File

@ -8,6 +8,7 @@ import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.plugin.NotarizedRoute
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.SchemaConfigurator
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.oas.payload.Parameter
@ -51,6 +52,7 @@ private fun Application.mainModule() {
schemaConfigurator = JacksonSchemaConfigurator()
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
route("/{id}") {

View File

@ -3,6 +3,7 @@ package io.bkbn.kompendium.playground
import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.locations.NotarizedLocations
import io.bkbn.kompendium.oas.payload.Parameter
@ -72,6 +73,7 @@ private fun Application.mainModule() {
)
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
get<Listing> { listing ->
call.respondText("Listing ${listing.name}, page ${listing.page}")

View File

@ -3,6 +3,7 @@ package io.bkbn.kompendium.playground
import io.bkbn.kompendium.core.metadata.GetInfo
import io.bkbn.kompendium.core.plugin.NotarizedApplication
import io.bkbn.kompendium.core.routes.redoc
import io.bkbn.kompendium.core.routes.swagger
import io.bkbn.kompendium.json.schema.definition.TypeDefinition
import io.bkbn.kompendium.oas.payload.Parameter
import io.bkbn.kompendium.oas.serialization.KompendiumSerializersModule
@ -73,6 +74,7 @@ private fun Application.mainModule() {
)
}
routing {
swagger(pageTitle = "Simple API Docs")
redoc(pageTitle = "Simple API Docs")
get<ListingResource> { listing ->
call.respondText("Listing ${listing.name}, page ${listing.page}")

View File

@ -22,8 +22,8 @@ dependencies {
implementation(projects.kompendiumJsonSchema)
implementation("com.google.protobuf:protobuf-java:3.21.12")
implementation("org.jetbrains.kotlin:kotlin-reflect:1.8.0")
implementation("com.google.protobuf:protobuf-java:3.22.0")
implementation("org.jetbrains.kotlin:kotlin-reflect:1.8.10")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.4.1")
// Formatting

View File

@ -22,8 +22,8 @@ dependencies {
// IMPLEMENTATION
implementation(projects.kompendiumCore)
implementation("io.ktor:ktor-server-core:2.2.2")
implementation("io.ktor:ktor-server-resources:2.2.2")
implementation("io.ktor:ktor-server-core:2.2.3")
implementation("io.ktor:ktor-server-resources:2.2.3")
// TESTING