chore: prep for 3.12.0 release

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -12,6 +12,12 @@
 
 ## Released
 
+## [3.12.0] - March 14th, 2023
+
+### Added
+
+- Add support for swagger documentation
+
 ## [3.11.0] - January 5th, 2023
 
 ### Added

build.gradle.kts

@@ -1,12 +1,12 @@
 plugins {
-  kotlin("jvm") version "1.8.0" apply false
+  kotlin("jvm") version "1.8.10" apply false
-  kotlin("plugin.serialization") version "1.8.0" 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 {

core/build.gradle.kts

@@ -33,7 +33,6 @@ dependencies {
   implementation("io.ktor:ktor-server-html-builder:$ktorVersion")
   implementation("io.ktor:ktor-server-content-negotiation:$ktorVersion")
   implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
-  implementation("ch.qos.logback:logback-classic:1.4.5")
 
   // Formatting
   detektPlugins("io.gitlab.arturbosch.detekt:detekt-formatting:$detektVersion")
@@ -58,7 +57,7 @@ dependencies {
   testFixturesApi("io.ktor:ktor-client:$ktorVersion")
   testFixturesApi("io.ktor:ktor-client-cio:$ktorVersion")
 
-  testFixturesApi("dev.forst:ktor-api-key:2.2.1")
+  testFixturesApi("dev.forst:ktor-api-key:2.2.2")
 
   testFixturesApi("org.jetbrains.kotlinx:kotlinx-serialization-json:1.4.1")
 }

core/src/main/kotlin/io/bkbn/kompendium/core/routes/Redoc.kt

@@ -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") {

core/src/main/kotlin/io/bkbn/kompendium/core/routes/Swagger.kt

@@ -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()
+          }
+        }
+      }
+    }
+  }
+}

core/src/testFixtures/kotlin/io/bkbn/kompendium/core/fixtures/TestHelpers.kt

@@ -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()
     }

docs/concepts/enrichment.md

@@ -1,6 +1,5 @@
 Kompendium allows users to enrich their data types with additional information. This can be done by defining a
-`TypeEnrichment` object and passing it to the `enrich` function on the `NotarizedRoute` builder. Enrichments
+`TypeEnrichment` object and passing it to the `enrichment` parameter of the relevant `requestType` or `responseType`.
-can be added to any request or response.
 
 ```kotlin
 data class SimpleData(val a: String, val b: Int? = null)

gradle.properties

@@ -1,13 +1,14 @@
 # Kompendium
-project.version=3.11.0
+project.version=3.12.0
 # Kotlin
 kotlin.code.style=official
 # Gradle
 org.gradle.vfs.watch=true
 org.gradle.vfs.verbose=true
 org.gradle.jvmargs=-Xmx2000m
+org.gradle.parallel=true
 
 # Dependencies
-ktorVersion=2.2.2
+ktorVersion=2.2.3
-kotestVersion=5.5.4
+kotestVersion=5.5.5
 detektVersion=1.21.0

json-schema/build.gradle.kts

@@ -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

locations/build.gradle.kts

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

playground/build.gradle.kts

@@ -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-api:2.20.0")
-  implementation("org.apache.logging.log4j:log4j-core:2.19.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")
 

playground/src/main/kotlin/io/bkbn/kompendium/playground/AuthPlayground.kt

@@ -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}") {

playground/src/main/kotlin/io/bkbn/kompendium/playground/BasicPlayground.kt

@@ -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()

playground/src/main/kotlin/io/bkbn/kompendium/playground/CustomTypePlayground.kt

@@ -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}") {

playground/src/main/kotlin/io/bkbn/kompendium/playground/EnrichmentPlayground.kt

@@ -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 {

playground/src/main/kotlin/io/bkbn/kompendium/playground/ExceptionPlayground.kt

@@ -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}") {

playground/src/main/kotlin/io/bkbn/kompendium/playground/GsonSerializationPlayground.kt

@@ -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}") {

playground/src/main/kotlin/io/bkbn/kompendium/playground/HiddenDocsPlayground.kt

@@ -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()

playground/src/main/kotlin/io/bkbn/kompendium/playground/JacksonSerializationPlayground.kt

@@ -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}") {

playground/src/main/kotlin/io/bkbn/kompendium/playground/LocationPlayground.kt

@@ -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}")

playground/src/main/kotlin/io/bkbn/kompendium/playground/ResourcesPlayground.kt

@@ -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}")

protobuf-java-converter/build.gradle.kts

@@ -22,8 +22,8 @@ dependencies {
 
 
   implementation(projects.kompendiumJsonSchema)
-  implementation("com.google.protobuf:protobuf-java:3.21.12")
+  implementation("com.google.protobuf:protobuf-java:3.22.0")
-  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

resources/build.gradle.kts

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