fix: 将ktor-swagger-ui升级到3.2.0，并修复了一下文档相关错误

subitlab · Aug 9, 2024 · 11f5091 · 11f5091
1 parent 608eef5
commit 11f5091
Show file tree

Hide file tree

Showing 21 changed files with 239 additions and 206 deletions.
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -9,6 +9,7 @@ val hikaricp_version: String by project
 val koin_version: String by project
 val jline_version: String by project
 val swagger_ui_version: String by project
+val schema_kenerator_version: String by project
 
 plugins {
     kotlin("jvm") version "2.0.0"
@@ -43,6 +44,9 @@ dependencies {
     implementation("io.ktor:ktor-server-double-receive-jvm") // 重复接收
     implementation("io.ktor:ktor-server-rate-limit-jvm") // 限流
     implementation("io.github.smiley4:ktor-swagger-ui:$swagger_ui_version") // 创建api页面
+    implementation("io.github.smiley4:schema-kenerator-core:$schema_kenerator_version")
+    implementation("io.github.smiley4:schema-kenerator-swagger:$schema_kenerator_version")
+    implementation("io.github.smiley4:schema-kenerator-reflection:$schema_kenerator_version")
     implementation("com.sun.mail:javax.mail:1.6.2") // 邮件发送
 
     //mysql

diff --git a/gradle.properties b/gradle.properties
@@ -6,7 +6,8 @@ exposed_version=0.51.1
 hikaricp_version = 5.1.0
 koin_version=3.5.6
 jline_version=3.26.2
-swagger_ui_version=2.10.0
+swagger_ui_version=3.2.0
+schema_kenerator_version=1.1.0
 # database
 h2_version=2.2.224
 mysql_version=8.0.33

diff --git a/src/main/kotlin/subit/console/command/Color.kt b/src/main/kotlin/subit/console/command/Color.kt
@@ -31,13 +31,16 @@ object Color: TreeCommand(Test, Mode, Effect)
             for (color in SimpleAnsiColor.entries) sb.append("${color.value}${color.key}${AnsiStyle.RESET} ")
             sb.append("\n")
             sb.append("R:\n")
-            for (i in 0..Byte.MAX_VALUE) sb.append("${RGBAnsiColor.fromRGB(i, 0, 0)}$i${AnsiStyle.RESET} ")
+            for (i in 0.toUByte()..UByte.MAX_VALUE)
+                sb.append("${RGBAnsiColor.fromRGB(i.toInt(), 0, 0)}$i${AnsiStyle.RESET} ")
             sb.append("\n")
             sb.append("G:\n")
-            for (i in 0..Byte.MAX_VALUE) sb.append("${RGBAnsiColor.fromRGB(0, i, 0)}$i${AnsiStyle.RESET} ")
+            for (i in 0.toUByte()..UByte.MAX_VALUE)
+                sb.append("${RGBAnsiColor.fromRGB(0, i.toInt(), 0)}$i${AnsiStyle.RESET} ")
             sb.append("\n")
             sb.append("B:\n")
-            for (i in 0..Byte.MAX_VALUE) sb.append("${RGBAnsiColor.fromRGB(0, 0, i)}$i${AnsiStyle.RESET} ")
+            for (i in 0.toUByte()..UByte.MAX_VALUE)
+                sb.append("${RGBAnsiColor.fromRGB(0, 0, i.toInt())}$i${AnsiStyle.RESET} ")
             sb.toString().split("\n").forEach { CommandSet.out.println(it) }
             return true
         }

diff --git a/src/main/kotlin/subit/dataClasses/Aliases.kt b/src/main/kotlin/subit/dataClasses/Aliases.kt
@@ -24,10 +24,9 @@ interface Id<ID, T>: Comparable<ID> where T: Number, T: Comparable<T>, ID: Id<ID
     }
 }
 
-typealias RawBlockId = Int
 @JvmInline
 @Serializable
-value class BlockId(override val value: RawBlockId): Id<BlockId, RawBlockId>
+value class BlockId(override val value: Int): Id<BlockId, Int>
 {
     override fun toString(): String = value.toString()
 
@@ -39,10 +38,9 @@ value class BlockId(override val value: RawBlockId): Id<BlockId, RawBlockId>
     }
 }
 
-typealias RawUserId = Int
 @JvmInline
 @Serializable
-value class UserId(override val value: RawUserId): Id<UserId, RawUserId>
+value class UserId(override val value: Int): Id<UserId, Int>
 {
     override fun toString(): String = value.toString()
 
@@ -54,10 +52,9 @@ value class UserId(override val value: RawUserId): Id<UserId, RawUserId>
     }
 }
 
-typealias RawPostId = Long
 @JvmInline
 @Serializable
-value class PostId(override val value: RawPostId): Id<PostId, RawPostId>
+value class PostId(override val value: Long): Id<PostId, Long>
 {
     override fun toString(): String = value.toString()
 
@@ -69,10 +66,9 @@ value class PostId(override val value: RawPostId): Id<PostId, RawPostId>
     }
 }
 
-typealias RawCommentId = Long
 @JvmInline
 @Serializable
-value class CommentId(override val value: RawCommentId): Id<CommentId, RawCommentId>
+value class CommentId(override val value: Long): Id<CommentId, Long>
 {
     override fun toString(): String = value.toString()
 
@@ -84,10 +80,9 @@ value class CommentId(override val value: RawCommentId): Id<CommentId, RawCommen
     }
 }
 
-typealias RawReportId = Long
 @JvmInline
 @Serializable
-value class ReportId(override val value: RawReportId): Id<ReportId, RawReportId>
+value class ReportId(override val value: Long): Id<ReportId, Long>
 {
     override fun toString(): String = value.toString()
 
@@ -99,10 +94,9 @@ value class ReportId(override val value: RawReportId): Id<ReportId, RawReportId>
     }
 }
 
-typealias RawNoticeId = Long
 @JvmInline
 @Serializable
-value class NoticeId(override val value: RawNoticeId): Id<NoticeId, RawNoticeId>
+value class NoticeId(override val value: Long): Id<NoticeId, Long>
 {
     override fun toString(): String = value.toString()
 

diff --git a/src/main/kotlin/subit/plugin/ApiDocs.kt b/src/main/kotlin/subit/plugin/ApiDocs.kt
@@ -1,6 +1,11 @@
 package subit.plugin
 
 import io.github.smiley4.ktorswaggerui.SwaggerUI
+import io.github.smiley4.schemakenerator.reflection.processReflection
+import io.github.smiley4.schemakenerator.swagger.compileInlining
+import io.github.smiley4.schemakenerator.swagger.data.TitleType
+import io.github.smiley4.schemakenerator.swagger.generateSwaggerSchema
+import io.github.smiley4.schemakenerator.swagger.withAutoTitle
 import io.ktor.server.application.*
 import io.ktor.server.plugins.ratelimit.*
 
@@ -9,19 +14,22 @@ import io.ktor.server.plugins.ratelimit.*
  */
 fun Application.installApiDoc() = install(SwaggerUI)
 {
-    swagger()
-    {
-        swaggerUrl = "api-docs"
-        // 当直接访问根目录时跳转到/api-docs 因为根目录下没有内容
-        forwardRoot = true
-        // apidocs为了不对外暴露, 因此需要认证, 见Authentication插件
-        authentication = "auth-api-docs"
-    }
     info()
     {
         title = "论坛后端API文档"
         version = subit.version
         description = "SubIT论坛后端API文档"
     }
+    server {
+        url = "http://localhost:8080"
+    }
     this.ignoredRouteSelectors += RateLimitRouteSelector::class
+    schemas {
+        generator = {
+            it.processReflection()
+                .generateSwaggerSchema()
+                .withAutoTitle(TitleType.SIMPLE)
+                .compileInlining()
+        }
+    }
 }
diff --git a/src/main/kotlin/subit/plugin/DoubleReceive.kt b/src/main/kotlin/subit/plugin/DoubleReceive.kt
@@ -1,5 +1,6 @@
 package subit.plugin
 
+import io.ktor.http.*
 import io.ktor.server.application.*
 import io.ktor.server.plugins.doublereceive.*
 import io.ktor.server.request.*
@@ -9,4 +10,9 @@ import io.ktor.server.request.*
  *
  * 该插件可以让请求体被多次读取, 但是也会消耗更多的内存.
  */
-fun Application.installDoubleReceive() = install(DoubleReceive)
+fun Application.installDoubleReceive() = install(DoubleReceive)
+{
+    cacheRawRequest = true
+    excludeFromCache { call, _ -> !call.request.contentType().match(ContentType.Application.Json) } // 不缓存非json请求
+    useFileForCache { call -> (call.request.contentLength() ?: 0) > 64 * (1 shl 20) } // 超过64MB的请求体使用文件缓存
+}
diff --git a/src/main/kotlin/subit/router/Admin.kt b/src/main/kotlin/subit/router/Admin.kt
@@ -2,9 +2,7 @@
 
 package subit.router.admin
 
-import io.github.smiley4.ktorswaggerui.dsl.get
-import io.github.smiley4.ktorswaggerui.dsl.post
-import io.github.smiley4.ktorswaggerui.dsl.route
+import io.github.smiley4.ktorswaggerui.dsl.routing.*
 import io.ktor.server.application.*
 import io.ktor.server.routing.*
 import kotlinx.serialization.Serializable

diff --git a/src/main/kotlin/subit/router/Auth.kt b/src/main/kotlin/subit/router/Auth.kt
@@ -2,8 +2,7 @@
 
 package subit.router.auth
 
-import io.github.smiley4.ktorswaggerui.dsl.post
-import io.github.smiley4.ktorswaggerui.dsl.route
+import io.github.smiley4.ktorswaggerui.dsl.routing.*
 import io.ktor.server.application.*
 import io.ktor.server.plugins.ratelimit.*
 import io.ktor.server.routing.*
@@ -16,6 +15,7 @@ import subit.database.*
 import subit.plugin.RateLimit
 import subit.router.Context
 import subit.router.authenticated
+import subit.router.example
 import subit.router.get
 import subit.utils.*
 

diff --git a/src/main/kotlin/subit/router/BannedWords.kt b/src/main/kotlin/subit/router/BannedWords.kt
@@ -2,7 +2,7 @@
 
 package subit.router.bannedWords
 
-import io.github.smiley4.ktorswaggerui.dsl.*
+import io.github.smiley4.ktorswaggerui.dsl.routing.*
 import io.ktor.server.application.*
 import io.ktor.server.routing.*
 import kotlinx.serialization.Serializable
@@ -54,7 +54,7 @@ fun Route.bannedWords() = route("/bannedWord", {
             {
                 required = true
                 description = "违禁词汇"
-                example = "违禁词汇"
+                example("违禁词汇")
             }
         }
         response {
@@ -70,7 +70,7 @@ fun Route.bannedWords() = route("/bannedWord", {
             {
                 required = true
                 description = "违禁词汇"
-                example = "违禁词汇"
+                example("违禁词汇")
             }
             body<NewBannedWord>
             {

diff --git a/src/main/kotlin/subit/router/Block.kt b/src/main/kotlin/subit/router/Block.kt
@@ -2,7 +2,7 @@
 
 package subit.router.block
 
-import io.github.smiley4.ktorswaggerui.dsl.*
+import io.github.smiley4.ktorswaggerui.dsl.routing.*
 import io.ktor.server.application.*
 import io.ktor.server.routing.*
 import kotlinx.serialization.Serializable
@@ -41,7 +41,7 @@ fun Route.block() = route("/block", {
             }
         }
         response {
-            statuses<WarpBlockId>(HttpStatus.OK)
+            statuses<WarpBlockId>(HttpStatus.OK, example = WarpBlockId(BlockId(0)))
             statuses(HttpStatus.Forbidden, HttpStatus.Unauthorized)
         }
     }) { newBlock() }
@@ -50,7 +50,7 @@ fun Route.block() = route("/block", {
         description = "修改板块信息"
         request {
             authenticated(true)
-            pathParameter<RawBlockId>("id")
+            pathParameter<BlockId>("id")
             {
                 required = true
                 description = "板块ID"
@@ -71,7 +71,7 @@ fun Route.block() = route("/block", {
         description = "获取板块信息"
         request {
             authenticated(false)
-            pathParameter<RawBlockId>("id")
+            pathParameter<BlockId>("id")
             {
                 required = true
                 description = "板块ID"
@@ -87,7 +87,7 @@ fun Route.block() = route("/block", {
         description = "删除板块"
         request {
             authenticated(true)
-            pathParameter<RawBlockId>("id")
+            pathParameter<BlockId>("id")
             {
                 required = true
                 description = "板块ID"
@@ -119,7 +119,7 @@ fun Route.block() = route("/block", {
         request {
             authenticated(false)
             paged()
-            pathParameter<RawBlockId>("id")
+            pathParameter<BlockId>("id")
             {
                 required = true
                 description = "板块ID"

diff --git a/src/main/kotlin/subit/router/Comment.kt b/src/main/kotlin/subit/router/Comment.kt
@@ -2,10 +2,7 @@
 
 package subit.router.comment
 
-import io.github.smiley4.ktorswaggerui.dsl.delete
-import io.github.smiley4.ktorswaggerui.dsl.get
-import io.github.smiley4.ktorswaggerui.dsl.post
-import io.github.smiley4.ktorswaggerui.dsl.route
+import io.github.smiley4.ktorswaggerui.dsl.routing.*
 import io.ktor.server.application.*
 import io.ktor.server.plugins.ratelimit.*
 import io.ktor.server.routing.*
@@ -18,6 +15,7 @@ import subit.database.*
 import subit.plugin.RateLimit
 import subit.router.Context
 import subit.router.authenticated
+import subit.router.example
 import subit.router.get
 import subit.utils.HttpStatus
 import subit.utils.respond
@@ -33,7 +31,7 @@ fun Route.comment() = route("/comment", {
             description = "评论一个帖子"
             request {
                 authenticated(true)
-                pathParameter<RawPostId>("postId")
+                pathParameter<PostId>("postId")
                 {
                     required = true
                     description = "帖子id"
@@ -54,7 +52,7 @@ fun Route.comment() = route("/comment", {
             description = "评论一个评论"
             request {
                 authenticated(true)
-                pathParameter<RawCommentId>("commentId")
+                pathParameter<CommentId>("commentId")
                 {
                     required = true
                     description = "评论id"
@@ -76,7 +74,7 @@ fun Route.comment() = route("/comment", {
         description = "删除一个评论, 需要板块管理员权限"
         request {
             authenticated(true)
-            pathParameter<RawCommentId>("commentId")
+            pathParameter<CommentId>("commentId")
             {
                 required = true
                 description = "评论id"
@@ -92,7 +90,7 @@ fun Route.comment() = route("/comment", {
         description = "获取一个帖子的评论列表"
         request {
             authenticated(false)
-            pathParameter<RawPostId>("postId")
+            pathParameter<PostId>("postId")
             {
                 required = true
                 description = "帖子id"
@@ -108,7 +106,7 @@ fun Route.comment() = route("/comment", {
         description = "获取一个评论的评论列表"
         request {
             authenticated(false)
-            pathParameter<RawCommentId>("commentId")
+            pathParameter<CommentId>("commentId")
             {
                 required = true
                 description = "评论id"
@@ -124,7 +122,7 @@ fun Route.comment() = route("/comment", {
         description = "获取一个评论的信息"
         request {
             authenticated(false)
-            pathParameter<RawCommentId>("commentId")
+            pathParameter<CommentId>("commentId")
             {
                 required = true
                 description = "评论id"