Add a Kotlin DSL for endpoint documentation (#249)

Suwayomi · Nov 14, 2021 · b02884f · b02884f
1 parent 845b588
commit b02884f
Show file tree

Hide file tree

Showing 5 changed files with 450 additions and 11 deletions.
diff --git a/server/build.gradle.kts b/server/build.gradle.kts
@@ -16,7 +16,8 @@ dependencies {
     implementation("com.squareup.okio:okio:2.10.0")
 
     // Javalin api
-    implementation("io.javalin:javalin:4.0.0")
+    implementation("io.javalin:javalin:4.1.1")
+    implementation("io.javalin:javalin-openapi:4.1.1")
     // jackson version locked by javalin, ref: `io.javalin.core.util.OptionalDependency`
     val jacksonVersion = "2.12.4"
     implementation("com.fasterxml.jackson.core:jackson-databind:$jacksonVersion")

diff --git a/server/src/main/kotlin/suwayomi/tachidesk/manga/MangaAPI.kt b/server/src/main/kotlin/suwayomi/tachidesk/manga/MangaAPI.kt
@@ -52,7 +52,7 @@ object MangaAPI {
         }
 
         path("manga") {
-            get("{mangaId}", MangaController::retrieve)
+            get("{mangaId}", MangaController.retrieve)
             get("{mangaId}/thumbnail", MangaController::thumbnail)
 
             get("{mangaId}/category", MangaController::categoryList)

diff --git a/server/src/main/kotlin/suwayomi/tachidesk/manga/controller/MangaController.kt b/server/src/main/kotlin/suwayomi/tachidesk/manga/controller/MangaController.kt
@@ -13,20 +13,35 @@ import suwayomi.tachidesk.manga.impl.Chapter
 import suwayomi.tachidesk.manga.impl.Library
 import suwayomi.tachidesk.manga.impl.Manga
 import suwayomi.tachidesk.manga.impl.Page
+import suwayomi.tachidesk.manga.model.dataclass.MangaDataClass
 import suwayomi.tachidesk.server.JavalinSetup.future
+import suwayomi.tachidesk.server.util.handler
+import suwayomi.tachidesk.server.util.pathParam
+import suwayomi.tachidesk.server.util.queryParam
+import suwayomi.tachidesk.server.util.withOperation
 
 object MangaController {
     /** get manga info */
-    fun retrieve(ctx: Context) {
-        val mangaId = ctx.pathParam("mangaId").toInt()
-        val onlineFetch = ctx.queryParam("onlineFetch")?.toBoolean() ?: false
-
-        ctx.future(
-            future {
-                Manga.getManga(mangaId, onlineFetch)
+    val retrieve = handler(
+        pathParam<Int>("mangaId"),
+        queryParam("onlineFetch", false),
+        documentWith = {
+            withOperation {
+                summary("Get a manga")
+                description("Get a manga from the database using a specific id")
             }
-        )
-    }
+        },
+        behaviorOf = { ctx, mangaId, onlineFetch ->
+            ctx.future(
+                future {
+                    Manga.getManga(mangaId, onlineFetch)
+                }
+            )
+        },
+        withResults = {
+            json<MangaDataClass>("OK")
+        }
+    )
 
     /** manga thumbnail */
     fun thumbnail(ctx: Context) {

diff --git a/server/src/main/kotlin/suwayomi/tachidesk/server/JavalinSetup.kt b/server/src/main/kotlin/suwayomi/tachidesk/server/JavalinSetup.kt
@@ -11,6 +11,10 @@ import io.javalin.Javalin
 import io.javalin.apibuilder.ApiBuilder.path
 import io.javalin.core.security.RouteRole
 import io.javalin.http.staticfiles.Location
+import io.javalin.plugin.openapi.OpenApiOptions
+import io.javalin.plugin.openapi.OpenApiPlugin
+import io.javalin.plugin.openapi.ui.SwaggerOptions
+import io.swagger.v3.oas.models.info.Info
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
@@ -46,6 +50,7 @@ object JavalinSetup {
                 logger.info { "Serving webUI static files" }
                 config.addStaticFiles(applicationDirs.webUIRoot, Location.EXTERNAL)
                 config.addSinglePageRoot("/", applicationDirs.webUIRoot + "/index.html", Location.EXTERNAL)
+                config.registerPlugin(OpenApiPlugin(getOpenApiOptions()))
             }
 
             config.enableCorsForAllOrigins()
@@ -98,6 +103,21 @@ object JavalinSetup {
         }
     }
 
+    private fun getOpenApiOptions(): OpenApiOptions {
+        val applicationInfo = Info().apply {
+            version("1.0")
+            description("Tachidesk Api")
+        }
+        return OpenApiOptions(applicationInfo).apply {
+            path("/api/openapi.json")
+            swagger(
+                SwaggerOptions("/api/swagger-ui").apply {
+                    title("Tachidesk Swagger Documentation")
+                }
+            )
+        }
+    }
+
     object Auth {
         enum class Role : RouteRole { ANYONE, USER_READ, USER_WRITE }
     }