diff --git a/CHANGELOG.md b/CHANGELOG.md index 03991fa15..68eee7875 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,11 @@ ## Released +## [2.0.3] - February 7th, 2022 +### Changed +- Fixed swagger documentation bug +- Deprecated Swagger Webjar approach + ## [2.0.2] - February 4th, 2022 ### Added - `@Referenced` annotation enabling support for recursive models diff --git a/gradle.properties b/gradle.properties index 209a49e13..88f47a5a3 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,5 +1,5 @@ # Kompendium -project.version=2.0.2 +project.version=2.0.3 # Kotlin kotlin.code.style=official # Gradle diff --git a/kompendium-core/src/main/kotlin/io/bkbn/kompendium/core/routes/Redoc.kt b/kompendium-core/src/main/kotlin/io/bkbn/kompendium/core/routes/Redoc.kt index cfe22bf47..242ac46a7 100644 --- a/kompendium-core/src/main/kotlin/io/bkbn/kompendium/core/routes/Redoc.kt +++ b/kompendium-core/src/main/kotlin/io/bkbn/kompendium/core/routes/Redoc.kt @@ -25,7 +25,7 @@ fun Routing.redoc(pageTitle: String = "Docs", specUrl: String = "/openapi.json") call.respondHtml { head { title { - +"$pageTitle" + +pageTitle } meta { charset = "utf-8" diff --git a/kompendium-core/src/main/kotlin/io/bkbn/kompendium/core/routes/Swagger.kt b/kompendium-core/src/main/kotlin/io/bkbn/kompendium/core/routes/Swagger.kt new file mode 100644 index 000000000..baa18c867 --- /dev/null +++ b/kompendium-core/src/main/kotlin/io/bkbn/kompendium/core/routes/Swagger.kt @@ -0,0 +1,81 @@ +package io.bkbn.kompendium.core.routes + +import io.ktor.application.call +import io.ktor.html.respondHtml +import io.ktor.routing.Routing +import io.ktor.routing.get +import io.ktor.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 + * @param pageTitle Webpage title you wish to be displayed on your docs + * @param specUrl url to point Swagger to the OpenAPI json document + */ +fun Routing.swagger(pageTitle: String = "Docs", specUrl: String = "/openapi.json") { + route("/swagger-ui") { + 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@3.12.1/swagger-ui.css" + rel = "stylesheet" + } + } + body { + div { + id = "swagger-ui" + } + script { + src = "https://unpkg.com/swagger-ui-dist@3.12.1/swagger-ui-standalone-preset.js" + } + script { + src = "https://unpkg.com/swagger-ui-dist@3.12.1/swagger-ui-bundle.js" + } + unsafe { + +""" + + """.trimIndent() + } + } + } + } + } +} diff --git a/kompendium-playground/build.gradle.kts b/kompendium-playground/build.gradle.kts index d31a16e3b..9d7d75c5c 100644 --- a/kompendium-playground/build.gradle.kts +++ b/kompendium-playground/build.gradle.kts @@ -14,7 +14,6 @@ dependencies { implementation(projects.kompendiumCore) implementation(projects.kompendiumAuth) implementation(projects.kompendiumLocations) - implementation(projects.kompendiumSwaggerUi) // Ktor val ktorVersion: String by project diff --git a/kompendium-playground/src/main/kotlin/io/bkbn/kompendium/playground/SwaggerPlayground.kt b/kompendium-playground/src/main/kotlin/io/bkbn/kompendium/playground/SwaggerPlayground.kt index 682ec6f8f..6f4016ed2 100644 --- a/kompendium-playground/src/main/kotlin/io/bkbn/kompendium/playground/SwaggerPlayground.kt +++ b/kompendium-playground/src/main/kotlin/io/bkbn/kompendium/playground/SwaggerPlayground.kt @@ -2,8 +2,8 @@ package io.bkbn.kompendium.playground import io.bkbn.kompendium.core.Kompendium import io.bkbn.kompendium.core.Notarized.notarizedGet +import io.bkbn.kompendium.core.routes.swagger import io.bkbn.kompendium.playground.util.Util -import io.bkbn.kompendium.swagger.swaggerUI import io.ktor.application.Application import io.ktor.application.call import io.ktor.application.install @@ -43,7 +43,7 @@ private fun Application.mainModule() { // Configures the routes for our API routing { // This is all you need to do to add Swagger! Reachable at `/swagger-ui` - swaggerUI() + swagger() // Kompendium infers the route path from the Ktor Route. This will show up as the root path `/` notarizedGet(BasicPlaygroundToC.simpleGetExample) { call.respond(HttpStatusCode.OK, BasicModels.BasicResponse(c = UUID.randomUUID().toString())) diff --git a/kompendium-swagger-ui/src/main/kotlin/io/bkbn/kompendium/swagger/SwaggerUI.kt b/kompendium-swagger-ui/src/main/kotlin/io/bkbn/kompendium/swagger/SwaggerUI.kt index 03490cbf0..d8f62b9aa 100644 --- a/kompendium-swagger-ui/src/main/kotlin/io/bkbn/kompendium/swagger/SwaggerUI.kt +++ b/kompendium-swagger-ui/src/main/kotlin/io/bkbn/kompendium/swagger/SwaggerUI.kt @@ -5,6 +5,10 @@ import io.ktor.response.respondRedirect import io.ktor.routing.Routing import io.ktor.routing.get +@Deprecated( + "Webjar approach is deprecated", + replaceWith = ReplaceWith("swagger()", "io.bkbn.kompendium.core.routes.swagger") +) fun Routing.swaggerUI(openApiJsonUrl: String = "/openapi.json") { get("/swagger-ui") { call.respondRedirect("/webjars/swagger-ui/index.html?url=$openApiJsonUrl", true)