document all endpoints (#350)

* Document all endpoints

* Forgot about global endpoints

server/src/main/kotlin/suwayomi/tachidesk/manga/controller/SourceController.kt

@@ -7,7 +7,7 @@ package suwayomi.tachidesk.manga.controller
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
-import io.javalin.http.Context
+import io.javalin.http.HttpCode
 import kotlinx.serialization.decodeFromString
 import kotlinx.serialization.json.Json
 import org.kodein.di.DI
@@ -18,87 +18,205 @@ import suwayomi.tachidesk.manga.impl.Search
 import suwayomi.tachidesk.manga.impl.Search.FilterChange
 import suwayomi.tachidesk.manga.impl.Source
 import suwayomi.tachidesk.manga.impl.Source.SourcePreferenceChange
+import suwayomi.tachidesk.manga.model.dataclass.PagedMangaListDataClass
 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
+import javax.sound.sampled.SourceDataLine
 
 object SourceController {
     /** list of sources */
-    fun list(ctx: Context) {
-        ctx.json(Source.getSourceList())
-    }
+    val list = handler(
+        documentWith = {
+            withOperation {
+                summary("Sources list")
+                description("List of sources")
+            }
+        },
+        behaviorOf = { ctx ->
+            ctx.json(Source.getSourceList())
+        },
+        withResults = {
+            json<List<SourceDataLine>>(HttpCode.OK)
+        }
+    )
 
     /** fetch source with id `sourceId` */
-    fun retrieve(ctx: Context) {
-        val sourceId = ctx.pathParam("sourceId").toLong()
-        ctx.json(Source.getSource(sourceId)!!)
-    }
+    val retrieve = handler(
+        pathParam<Long>("sourceId"),
+        documentWith = {
+            withOperation {
+                summary("Source fetch")
+                description("Fetch source with id `sourceId`")
+            }
+        },
+        behaviorOf = { ctx, sourceId ->
+            ctx.json(Source.getSource(sourceId)!!)
+        },
+        withResults = {
+            json<SourceDataLine>(HttpCode.OK)
+            httpCode(HttpCode.NOT_FOUND)
+        }
+    )
 
     /** popular mangas from source with id `sourceId` */
-    fun popular(ctx: Context) {
-        val sourceId = ctx.pathParam("sourceId").toLong()
-        val pageNum = ctx.pathParam("pageNum").toInt()
-        ctx.future(
-            future {
-                MangaList.getMangaList(sourceId, pageNum, popular = true)
+    val popular = handler(
+        pathParam<Long>("sourceId"),
+        pathParam<Int>("pageNum"),
+        documentWith = {
+            withOperation {
+                summary("Source popular manga")
+                description("Popular mangas from source with id `sourceId`")
             }
-        )
-    }
+        },
+        behaviorOf = { ctx, sourceId, pageNum ->
+            ctx.future(
+                future {
+                    MangaList.getMangaList(sourceId, pageNum, popular = true)
+                }
+            )
+        },
+        withResults = {
+            json<PagedMangaListDataClass>(HttpCode.OK)
+        }
+    )
 
     /** latest mangas from source with id `sourceId` */
-    fun latest(ctx: Context) {
-        val sourceId = ctx.pathParam("sourceId").toLong()
-        val pageNum = ctx.pathParam("pageNum").toInt()
-        ctx.future(
-            future {
-                MangaList.getMangaList(sourceId, pageNum, popular = false)
+    val latest = handler(
+        pathParam<Long>("sourceId"),
+        pathParam<Int>("pageNum"),
+        documentWith = {
+            withOperation {
+                summary("Source latest manga")
+                description("Latest mangas from source with id `sourceId`")
             }
-        )
-    }
+        },
+        behaviorOf = { ctx, sourceId, pageNum ->
+            ctx.future(
+                future {
+                    MangaList.getMangaList(sourceId, pageNum, popular = false)
+                }
+            )
+        },
+        withResults = {
+            json<PagedMangaListDataClass>(HttpCode.OK)
+        }
+    )
 
     /** fetch preferences of source with id `sourceId` */
-    fun getPreferences(ctx: Context) {
-        val sourceId = ctx.pathParam("sourceId").toLong()
-        ctx.json(Source.getSourcePreferences(sourceId))
-    }
+    val getPreferences = handler(
+        pathParam<Long>("sourceId"),
+        documentWith = {
+            withOperation {
+                summary("Source preferences")
+                description("Fetch preferences of source with id `sourceId`")
+            }
+        },
+        behaviorOf = { ctx, sourceId ->
+            ctx.json(Source.getSourcePreferences(sourceId))
+
+        },
+        withResults = {
+            json<List<Source.PreferenceObject>>(HttpCode.OK)
+        }
+    )
 
     /** set one preference of source with id `sourceId` */
-    fun setPreference(ctx: Context) {
-        val sourceId = ctx.pathParam("sourceId").toLong()
-        val preferenceChange = ctx.bodyAsClass(SourcePreferenceChange::class.java)
-        ctx.json(Source.setSourcePreference(sourceId, preferenceChange))
-    }
+    val setPreference = handler(
+        pathParam<Long>("sourceId"),
+        documentWith = {
+            withOperation {
+                summary("Source preference set")
+                description("Set one preference of source with id `sourceId`")
+            }
+        },
+        behaviorOf = { ctx, sourceId ->
+            val preferenceChange = ctx.bodyAsClass(SourcePreferenceChange::class.java)
+            ctx.json(Source.setSourcePreference(sourceId, preferenceChange))
+        },
+        withResults = {
+            httpCode(HttpCode.OK)
+        }
+    )
 
     /** fetch filters of source with id `sourceId` */
-    fun getFilters(ctx: Context) {
-        val sourceId = ctx.pathParam("sourceId").toLong()
-        val reset = ctx.queryParam("reset")?.toBoolean() ?: false
-        ctx.json(Search.getFilterList(sourceId, reset))
-    }
+    val getFilters = handler(
+        pathParam<Long>("sourceId"),
+        queryParam("reset", false),
+        documentWith = {
+            withOperation {
+                summary("Source filters")
+                description("Fetch filters of source with id `sourceId`")
+            }
+        },
+        behaviorOf = { ctx, sourceId, reset ->
+            ctx.json(Search.getFilterList(sourceId, reset))
+        },
+        withResults = {
+            json<List<Search.FilterObject>>(HttpCode.OK)
+        }
+    )
 
     private val json by DI.global.instance<Json>()
 
     /** change filters of source with id `sourceId` */
-    fun setFilters(ctx: Context) {
-        val sourceId = ctx.pathParam("sourceId").toLong()
-        val filterChange = try {
-            json.decodeFromString<List<FilterChange>>(ctx.body())
-        } catch (e: Exception) {
-            listOf(json.decodeFromString<FilterChange>(ctx.body()))
-        }
+    val setFilters = handler(
+        pathParam<Long>("sourceId"),
+        documentWith = {
+            withOperation {
+                summary("Source filters set")
+                description("Change filters of source with id `sourceId`")
+            }
+        },
+        behaviorOf = { ctx, sourceId ->
+            val filterChange = try {
+                json.decodeFromString<List<FilterChange>>(ctx.body())
+            } catch (e: Exception) {
+                listOf(json.decodeFromString<FilterChange>(ctx.body()))
+            }
 
-        ctx.json(Search.setFilter(sourceId, filterChange))
-    }
+            ctx.json(Search.setFilter(sourceId, filterChange))
+        },
+        withResults = {
+            httpCode(HttpCode.OK)
+        }
+    )
 
     /** single source search */
-    fun searchSingle(ctx: Context) {
-        val sourceId = ctx.pathParam("sourceId").toLong()
-        val searchTerm = ctx.queryParam("searchTerm") ?: ""
-        val pageNum = ctx.queryParam("pageNum")?.toInt() ?: 1
-        ctx.future(future { Search.sourceSearch(sourceId, searchTerm, pageNum) })
-    }
+    val searchSingle = handler(
+        pathParam<Long>("sourceId"),
+        queryParam("searchTerm", ""),
+        queryParam("pageNum", 1),
+        documentWith = {
+            withOperation {
+                summary("Source search")
+                description("Single source search")
+            }
+        },
+        behaviorOf = { ctx, sourceId, searchTerm, pageNum ->
+            ctx.future(future { Search.sourceSearch(sourceId, searchTerm, pageNum) })
+        },
+        withResults = {
+            json<PagedMangaListDataClass>(HttpCode.OK)
+        }
+    )
 
     /** all source search */
-    fun searchAll(ctx: Context) { // TODO
-        val searchTerm = ctx.pathParam("searchTerm")
-        ctx.json(Search.sourceGlobalSearch(searchTerm))
-    }
+    val searchAll = handler(
+        pathParam<String>("searchTerm"),
+        documentWith = {
+            withOperation {
+                summary("Source global search")
+                description("All source search")
+            }
+        },
+        behaviorOf = { ctx, searchTerm -> // TODO
+            ctx.json(Search.sourceGlobalSearch(searchTerm))
+        },
+        withResults = {
+            httpCode(HttpCode.OK)
+        }
+    )
 }