feat(openapi): provide swagger ui of model-server.yaml at endpoint /swagger

Author: nkoester

api/model-server-deprecated.yaml

@@ -11,10 +11,10 @@ openapi: "3.0.3"
 info:
   title: "model-server deprecated API"
   description: "modelix deprecated API"
-  version: "0.0.1"
+  version: "1.0.0"
 servers:
-  - url: 'http://127.0.0.1:28101'
-    description: local model-server
+  - url: '/'
+    description: model-server
 paths:
   /json:
     get:

api/model-server-html.yaml

@@ -13,10 +13,10 @@ openapi: "3.0.3"
 info:
   title: "model-server content browser API"
   description: "modelix content browser API"
-  version: "0.0.1"
+  version: "1.0.0"
 servers:
-  - url: 'http://127.0.0.1:28101'
-    description: local model-server
+  - url: '/'
+    description: model-server
 paths:
   /:
     get:

api/model-server-light.yaml

@@ -11,10 +11,10 @@ openapi: "3.0.3"
 info:
   title: "model-server light API"
   description: "modelix light API"
-  version: "0.0.1"
+  version: "1.0.0"
 servers:
-  - url: 'http://127.0.0.1:28101'
-    description: local model-server
+  - url: '/'
+    description: model-server
 paths:
   # TODO: this is a WS, openAPI will not help here
   /json/v2/{repositoryId}/ws:

api/model-server.yaml

@@ -11,10 +11,10 @@ openapi: "3.0.3"
 info:
   title: "model-server public API"
   description: "modelix public API"
-  version: "0.0.1"
+  version: "1.0.0"
 servers:
-  - url: 'http://127.0.0.1:28101'
-    description: local model-server
+  - url: '/'
+    description: model-server
 paths:
   /v2/server-id:
     get:

gradle/libs.versions.toml

@@ -60,6 +60,7 @@ ktor-server-status-pages = { group = "io.ktor", name = "ktor-server-status-pages
 ktor-server-test-host = { group = "io.ktor", name = "ktor-server-test-host", version.ref = "ktor" }
 ktor-server-websockets = { group = "io.ktor", name = "ktor-server-websockets", version.ref = "ktor" }
 ktor-server-resources = { group = "io.ktor", name = "ktor-server-resources", version.ref = "ktor" }
+ktor-server-swagger = { group = "io.ktor", name = "ktor-server-swagger", version.ref = "ktor" }
 
 ktor-client-core = { group = "io.ktor", name = "ktor-client-core", version.ref = "ktor" }
 ktor-client-content-negotiation = { group = "io.ktor", name = "ktor-client-content-negotiation", version.ref = "ktor" }

model-server/build.gradle.kts

@@ -52,6 +52,7 @@ dependencies {
     implementation(libs.ktor.server.content.negotiation)
     implementation(libs.ktor.server.resources)
     implementation(libs.ktor.serialization.json)
+    implementation(libs.ktor.server.swagger)
 
     implementation(libs.bundles.ignite)
 
@@ -190,7 +191,7 @@ spotless {
 
 // OpenAPI integration
 val basePackage = project.group.toString()
-val openAPIgenerationPath = "${project.layout.buildDirectory}/generated/openapi"
+val openAPIgenerationPath = "${project.layout.buildDirectory.get()}/generated/openapi"
 
 // Pairs of the different OpenAPI files we use. Each pair must have its own 'category' as first argument as these
 // are used to generate corresponding packages

model-server/src/main/kotlin/org/modelix/model/server/CmdLineArgs.kt

@@ -40,6 +40,9 @@ internal class CmdLineArgs {
     )
     var schemaInit = false
 
+    @Parameter(names = ["-noswagger"], description = "Disables SwaggerUI at endpoint '/swagger'", converter = BooleanConverter::class)
+    var noSwaggerUi: Boolean = false
+
     @Parameter(names = ["-h", "--help"], help = true)
     var help = false
 }

model-server/src/main/kotlin/org/modelix/model/server/Main.kt

@@ -29,6 +29,7 @@ import io.ktor.server.netty.NettyApplicationEngine
 import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
 import io.ktor.server.plugins.cors.routing.CORS
 import io.ktor.server.plugins.forwardedheaders.ForwardedHeaders
+import io.ktor.server.plugins.swagger.swaggerUI
 import io.ktor.server.resources.Resources
 import io.ktor.server.response.respondText
 import io.ktor.server.routing.IgnoreTrailingSlash
@@ -90,6 +91,8 @@ object Main {
         LOG.info("Path to JDBC configuration file: " + cmdLineArgs.jdbcConfFile)
         LOG.info("Schema initialization: " + cmdLineArgs.schemaInit)
         LOG.info("Set values: " + cmdLineArgs.setValues)
+        LOG.info("Disable Swagger-UI: " + cmdLineArgs.noSwaggerUi)
+
         if (cmdLineArgs.dumpOutName != null && !cmdLineArgs.inmemory) {
             throw RuntimeException("For now dumps are supported only with the inmemory option")
         }
@@ -224,11 +227,21 @@ object Main {
                                     li {
                                         a("user") { +"View JWT token and permissions" }
                                     }
+                                    li {
+                                        a("swagger") { +"SwaggerUI" }
+                                    }
                                 }
                             }
                         }
                         call.respondText("Model Server")
                     }
+                    if (cmdLineArgs.noSwaggerUi) {
+                        get("swagger") {
+                            call.respondText("SwaggerUI is disabled")
+                        }
+                    } else {
+                        swaggerUI(path = "swagger", swaggerFile = "../api/model-server.yaml")
+                    }
                 }
             }
             ktorServer.start(wait = true)

model-server/src/main/kotlin/org/modelix/model/server/handlers/ModelReplicationServer.kt

@@ -25,7 +25,6 @@ import io.ktor.server.resources.post
 import io.ktor.server.response.respond
 import io.ktor.server.response.respondText
 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 io.ktor.server.websocket.webSocket

model-server/src/main/kotlin/org/modelix/model/server/templates/PageWithMenuBar.kt

@@ -39,6 +39,7 @@ class PageWithMenuBar(val activePage: String, val baseUrl: String) : Template<HT
                     "json/" to "JSON API",
                     "headers" to "HTTP Headers",
                     "user" to "JWT token and permissions",
+                    "swagger" to "SwaggerUI",
                 )
                 var classes = "menuItem"
                 if (activePage == "root") {