breaking change: V3 alpha (#256)

playground/Module.md

@@ -0,0 +1,3 @@
+# Module kompendium-playground
+
+This module contains a number of examples showcasing the capabilities of Kompendium

playground/build.gradle.kts

@@ -0,0 +1,44 @@
+plugins {
+  kotlin("jvm")
+  kotlin("plugin.serialization")
+  id("io.bkbn.sourdough.application.jvm")
+  id("application")
+}
+
+sourdoughApp {
+  compilerArgs.set(listOf("-opt-in=kotlin.RequiresOptIn"))
+}
+
+dependencies {
+  // IMPLEMENTATION
+  implementation(projects.kompendiumCore)
+  implementation(projects.kompendiumLocations)
+
+  // Ktor
+  val ktorVersion: String by project
+
+  implementation("io.ktor:ktor-server-core:$ktorVersion")
+  implementation("io.ktor:ktor-server-netty:$ktorVersion")
+  implementation("io.ktor:ktor-server-auth:$ktorVersion")
+  implementation("io.ktor:ktor-server-auth-jwt:$ktorVersion")
+  implementation("io.ktor:ktor-serialization:$ktorVersion")
+  implementation("io.ktor:ktor-server-status-pages:$ktorVersion")
+  implementation("io.ktor:ktor-server-content-negotiation:$ktorVersion")
+  implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
+  implementation("io.ktor:ktor-serialization-jackson:$ktorVersion")
+  implementation("io.ktor:ktor-serialization-gson:$ktorVersion")
+  implementation("io.ktor:ktor-server-locations:$ktorVersion")
+
+  // Logging
+  implementation("org.apache.logging.log4j:log4j-api-kotlin:1.2.0")
+  implementation("org.apache.logging.log4j:log4j-api:2.17.2")
+  implementation("org.apache.logging.log4j:log4j-core:2.18.0")
+  implementation("org.slf4j:slf4j-api:1.7.36")
+  implementation("org.slf4j:slf4j-simple:1.7.36")
+
+
+  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.3")
+  implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.0")
+
+  implementation("joda-time:joda-time:2.10.14")
+}

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

@@ -0,0 +1,115 @@
+package io.bkbn.kompendium.playground
+
+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.json.schema.definition.TypeDefinition
+import io.bkbn.kompendium.oas.component.Components
+import io.bkbn.kompendium.oas.payload.Parameter
+import io.bkbn.kompendium.oas.security.BasicAuth
+import io.bkbn.kompendium.oas.serialization.KompendiumSerializersModule
+import io.bkbn.kompendium.playground.util.ExampleResponse
+import io.bkbn.kompendium.playground.util.Util.baseSpec
+import io.ktor.http.HttpStatusCode
+import io.ktor.serialization.kotlinx.json.json
+import io.ktor.server.application.Application
+import io.ktor.server.application.call
+import io.ktor.server.application.install
+import io.ktor.server.auth.Authentication
+import io.ktor.server.auth.UserIdPrincipal
+import io.ktor.server.auth.authenticate
+import io.ktor.server.auth.basic
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.netty.Netty
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.server.response.respond
+import io.ktor.server.routing.Route
+import io.ktor.server.routing.get
+import io.ktor.server.routing.route
+import io.ktor.server.routing.routing
+import kotlinx.serialization.json.Json
+
+/**
+ * Application entrypoint.  Run this and head on over to `localhost:8081/docs`
+ * to see a very simple yet beautifully documented API
+ */
+fun main() {
+  embeddedServer(
+    Netty,
+    port = 8081,
+    module = Application::mainModule
+  ).start(wait = true)
+}
+
+private fun Application.mainModule() {
+  // Installs Simple JSON Content Negotiation
+  install(ContentNegotiation) {
+    json(Json {
+      serializersModule = KompendiumSerializersModule.module
+      encodeDefaults = true
+      explicitNulls = false
+    })
+  }
+  install(Authentication) {
+    basic("basic") {
+      realm = "Ktor Server"
+      validate { credentials ->
+        if (credentials.name == credentials.password) {
+          UserIdPrincipal(credentials.name)
+        } else {
+          null
+        }
+      }
+    }
+  }
+  install(NotarizedApplication()) {
+    spec = baseSpec.copy(
+      components = Components(
+        securitySchemes = mutableMapOf(
+          "basic" to BasicAuth()
+        )
+      )
+    )
+  }
+  routing {
+    redoc(pageTitle = "Simple API Docs")
+    authenticate("basic") {
+      // This adds ReDoc support at the `/docs` endpoint.
+      // By default, it will point at the `/openapi.json` created by Kompendium
+
+      // Route with a get handler
+      route("/{id}") {
+        idDocumentation()
+        get {
+          call.respond(HttpStatusCode.OK, ExampleResponse(true))
+        }
+      }
+    }
+  }
+}
+
+// Documentation for our route
+private fun Route.idDocumentation() {
+  install(NotarizedRoute()) {
+    parameters = listOf(
+      Parameter(
+        name = "id",
+        `in` = Parameter.Location.path,
+        schema = TypeDefinition.STRING
+      )
+    )
+    get = GetInfo.builder {
+      summary("Get user by id")
+      description("A very neat endpoint!")
+      security = mapOf(
+        "basic" to emptyList()
+      )
+      response {
+        responseCode(HttpStatusCode.OK)
+        responseType<ExampleResponse>()
+        description("Will return whether or not the user is real 😱")
+      }
+    }
+  }
+}

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

@@ -0,0 +1,77 @@
+package io.bkbn.kompendium.playground
+
+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.json.schema.definition.TypeDefinition
+import io.bkbn.kompendium.oas.payload.Parameter
+import io.bkbn.kompendium.oas.serialization.KompendiumSerializersModule
+import io.bkbn.kompendium.playground.util.ExampleResponse
+import io.bkbn.kompendium.playground.util.Util.baseSpec
+import io.ktor.http.HttpStatusCode
+import io.ktor.serialization.kotlinx.json.json
+import io.ktor.server.application.Application
+import io.ktor.server.application.call
+import io.ktor.server.application.install
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.netty.Netty
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.server.response.respond
+import io.ktor.server.routing.Route
+import io.ktor.server.routing.get
+import io.ktor.server.routing.route
+import io.ktor.server.routing.routing
+import kotlinx.serialization.json.Json
+
+fun main() {
+  embeddedServer(
+    Netty,
+    port = 8081,
+    module = Application::mainModule
+  ).start(wait = true)
+}
+
+private fun Application.mainModule() {
+  install(ContentNegotiation) {
+    json(Json {
+      serializersModule = KompendiumSerializersModule.module
+      encodeDefaults = true
+      explicitNulls = false
+    })
+  }
+  install(NotarizedApplication()) {
+    spec = baseSpec
+  }
+  routing {
+    redoc(pageTitle = "Simple API Docs")
+
+    route("/{id}") {
+      idDocumentation()
+      get {
+        call.respond(HttpStatusCode.OK, ExampleResponse(true))
+      }
+    }
+  }
+}
+
+private fun Route.idDocumentation() {
+  install(NotarizedRoute()) {
+    parameters = listOf(
+      Parameter(
+        name = "id",
+        `in` = Parameter.Location.path,
+        schema = TypeDefinition.STRING
+      )
+    )
+    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 😱")
+      }
+    }
+  }
+}

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

@@ -0,0 +1,90 @@
+package io.bkbn.kompendium.playground
+
+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.json.schema.definition.TypeDefinition
+import io.bkbn.kompendium.oas.payload.Parameter
+import io.bkbn.kompendium.oas.serialization.KompendiumSerializersModule
+import io.bkbn.kompendium.playground.util.CustomTypeResponse
+import io.bkbn.kompendium.playground.util.Util.baseSpec
+import io.ktor.http.HttpStatusCode
+import io.ktor.serialization.kotlinx.json.json
+import io.ktor.server.application.Application
+import io.ktor.server.application.call
+import io.ktor.server.application.install
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.netty.Netty
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.server.response.respond
+import io.ktor.server.routing.Route
+import io.ktor.server.routing.get
+import io.ktor.server.routing.route
+import io.ktor.server.routing.routing
+import kotlin.reflect.typeOf
+import kotlinx.datetime.Clock
+import kotlinx.datetime.Instant
+import kotlinx.serialization.json.Json
+import java.util.UUID
+
+fun main() {
+  embeddedServer(
+    Netty,
+    port = 8081,
+    module = Application::mainModule
+  ).start(wait = true)
+}
+
+private fun Application.mainModule() {
+  install(ContentNegotiation) {
+    json(Json {
+      serializersModule = KompendiumSerializersModule.module
+      encodeDefaults = true
+      explicitNulls = false
+    })
+  }
+  install(NotarizedApplication()) {
+    spec = baseSpec
+    customTypes = mapOf(
+      typeOf<Instant>() to TypeDefinition(type = "string", format = "date-time")
+    )
+  }
+  routing {
+    redoc(pageTitle = "Simple API Docs")
+
+    route("/{id}") {
+      idDocumentation()
+      get {
+        call.respond(
+          HttpStatusCode.OK,
+          CustomTypeResponse(
+            thing = UUID.randomUUID().toString(),
+            timestamp = Clock.System.now()
+          )
+        )
+      }
+    }
+  }
+}
+
+private fun Route.idDocumentation() {
+  install(NotarizedRoute()) {
+    parameters = listOf(
+      Parameter(
+        name = "id",
+        `in` = Parameter.Location.path,
+        schema = TypeDefinition.STRING
+      )
+    )
+    get = GetInfo.builder {
+      summary("Important Thing")
+      description("Do this often, it's important!")
+      response {
+        responseCode(HttpStatusCode.OK)
+        responseType<CustomTypeResponse>()
+        description("Showcases using a custom type!")
+      }
+    }
+  }
+}

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

@@ -0,0 +1,90 @@
+package io.bkbn.kompendium.playground
+
+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.json.schema.definition.TypeDefinition
+import io.bkbn.kompendium.oas.payload.Parameter
+import io.bkbn.kompendium.oas.serialization.KompendiumSerializersModule
+import io.bkbn.kompendium.playground.util.ExampleResponse
+import io.bkbn.kompendium.playground.util.ExceptionResponse
+import io.bkbn.kompendium.playground.util.Util.baseSpec
+import io.ktor.http.HttpStatusCode
+import io.ktor.serialization.kotlinx.json.json
+import io.ktor.server.application.Application
+import io.ktor.server.application.call
+import io.ktor.server.application.install
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.netty.Netty
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.server.plugins.statuspages.StatusPages
+import io.ktor.server.response.respond
+import io.ktor.server.routing.Route
+import io.ktor.server.routing.get
+import io.ktor.server.routing.route
+import io.ktor.server.routing.routing
+import kotlinx.serialization.json.Json
+import java.lang.RuntimeException
+
+fun main() {
+  embeddedServer(
+    Netty,
+    port = 8081,
+    module = Application::mainModule
+  ).start(wait = true)
+}
+
+private fun Application.mainModule() {
+  install(ContentNegotiation) {
+    json(Json {
+      serializersModule = KompendiumSerializersModule.module
+      encodeDefaults = true
+      explicitNulls = false
+    })
+  }
+  install(NotarizedApplication()) {
+    spec = baseSpec
+  }
+  install(StatusPages) {
+    exception<Throwable> { call, _ ->
+      call.respond(HttpStatusCode.InternalServerError, ExceptionResponse("Bad Thing Happened!"))
+    }
+  }
+  routing {
+    redoc(pageTitle = "Simple API Docs")
+
+    route("/{id}") {
+      idDocumentation()
+      get {
+        throw RuntimeException("This wasn't your fault I promise <3")
+      }
+    }
+  }
+}
+
+private fun Route.idDocumentation() {
+  install(NotarizedRoute()) {
+    parameters = listOf(
+      Parameter(
+        name = "id",
+        `in` = Parameter.Location.path,
+        schema = TypeDefinition.STRING
+      )
+    )
+    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 😱")
+        canRespond {
+          description("Bad Things Happened")
+          responseCode(HttpStatusCode.InternalServerError)
+          responseType<ExceptionResponse>()
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,73 @@
+package io.bkbn.kompendium.playground
+
+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.json.schema.definition.TypeDefinition
+import io.bkbn.kompendium.oas.payload.Parameter
+import io.bkbn.kompendium.playground.util.ExampleResponse
+import io.bkbn.kompendium.playground.util.Util.baseSpec
+import io.ktor.http.HttpStatusCode
+import io.ktor.serialization.gson.gson
+import io.ktor.server.application.Application
+import io.ktor.server.application.call
+import io.ktor.server.application.install
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.netty.Netty
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.server.response.respond
+import io.ktor.server.routing.Route
+import io.ktor.server.routing.get
+import io.ktor.server.routing.route
+import io.ktor.server.routing.routing
+
+fun main() {
+  embeddedServer(
+    Netty,
+    port = 8081,
+    module = Application::mainModule
+  ).start(wait = true)
+}
+
+private fun Application.mainModule() {
+  install(ContentNegotiation) {
+    gson {
+      setPrettyPrinting()
+    }
+  }
+  install(NotarizedApplication()) {
+    spec = baseSpec
+  }
+  routing {
+    redoc(pageTitle = "Simple API Docs")
+
+    route("/{id}") {
+      idDocumentation()
+      get {
+        call.respond(HttpStatusCode.OK, ExampleResponse(true))
+      }
+    }
+  }
+}
+
+private fun Route.idDocumentation() {
+  install(NotarizedRoute()) {
+    parameters = listOf(
+      Parameter(
+        name = "id",
+        `in` = Parameter.Location.path,
+        schema = TypeDefinition.STRING
+      )
+    )
+    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 😱")
+      }
+    }
+  }
+}

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

@@ -0,0 +1,77 @@
+package io.bkbn.kompendium.playground
+
+import com.fasterxml.jackson.annotation.JsonInclude
+import com.fasterxml.jackson.databind.SerializationFeature
+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.json.schema.definition.TypeDefinition
+import io.bkbn.kompendium.oas.payload.Parameter
+import io.bkbn.kompendium.playground.util.ExampleResponse
+import io.bkbn.kompendium.playground.util.Util.baseSpec
+import io.ktor.http.HttpStatusCode
+import io.ktor.serialization.jackson.jackson
+import io.ktor.server.application.Application
+import io.ktor.server.application.call
+import io.ktor.server.application.install
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.netty.Netty
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.server.response.respond
+import io.ktor.server.routing.Route
+import io.ktor.server.routing.get
+import io.ktor.server.routing.route
+import io.ktor.server.routing.routing
+
+fun main() {
+  embeddedServer(
+    Netty,
+    port = 8081,
+    module = Application::mainModule
+  ).start(wait = true)
+}
+
+private fun Application.mainModule() {
+  install(ContentNegotiation) {
+    jackson {
+      enable(SerializationFeature.INDENT_OUTPUT)
+      setSerializationInclusion(JsonInclude.Include.NON_NULL)
+    }
+  }
+  install(NotarizedApplication()) {
+    spec = baseSpec
+  }
+  routing {
+    redoc(pageTitle = "Simple API Docs")
+
+    route("/{id}") {
+      idDocumentation()
+      get {
+        call.respond(HttpStatusCode.OK, ExampleResponse(true))
+      }
+    }
+  }
+}
+
+private fun Route.idDocumentation() {
+  install(NotarizedRoute()) {
+    parameters = listOf(
+      Parameter(
+        name = "id",
+        `in` = Parameter.Location.path,
+        schema = TypeDefinition.STRING
+      )
+    )
+    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 😱")
+      }
+    }
+  }
+}
+

playground/src/main/kotlin/io/bkbn/kompendium/playground/util/Models.kt

@@ -0,0 +1,16 @@
+package io.bkbn.kompendium.playground.util
+
+import kotlinx.datetime.Instant
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class ExampleResponse(val isReal: Boolean)
+
+@Serializable
+data class CustomTypeResponse(
+  val thing: String,
+  val timestamp: Instant
+)
+
+@Serializable
+data class ExceptionResponse(val message: String)

playground/src/main/kotlin/io/bkbn/kompendium/playground/util/Util.kt

@@ -0,0 +1,40 @@
+package io.bkbn.kompendium.playground.util
+
+import io.bkbn.kompendium.oas.OpenApiSpec
+import io.bkbn.kompendium.oas.info.Contact
+import io.bkbn.kompendium.oas.info.Info
+import io.bkbn.kompendium.oas.info.License
+import io.bkbn.kompendium.oas.server.Server
+import kotlinx.serialization.ExperimentalSerializationApi
+import java.net.URI
+
+object Util {
+  val baseSpec = OpenApiSpec(
+    info = Info(
+      title = "Simple Demo API",
+      version = "1.33.7",
+      description = "Wow isn't this cool?",
+      termsOfService = URI("https://example.com"),
+      contact = Contact(
+        name = "Homer Simpson",
+        email = "chunkylover53@aol.com",
+        url = URI("https://gph.is/1NPUDiM")
+      ),
+      license = License(
+        name = "MIT",
+        url = URI("https://github.com/bkbnio/kompendium/blob/main/LICENSE")
+      )
+    ),
+    servers = mutableListOf(
+      Server(
+        url = URI("https://myawesomeapi.com"),
+        description = "Production instance of my API"
+      ),
+      Server(
+        url = URI("https://staging.myawesomeapi.com"),
+        description = "Where the fun stuff happens"
+      )
+    )
+  )
+
+}

playground/src/main/resources/logback.xml

@@ -0,0 +1,14 @@
+<configuration>
+  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+    <encoder>
+      <pattern>%d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+    </encoder>
+  </appender>
+
+  <root level="trace">
+    <appender-ref ref="STDOUT"/>
+  </root>
+
+  <logger name="org.eclipse.jetty" level="INFO"/>
+  <logger name="io.netty" level="INFO"/>
+</configuration>