Ktor API (Kotlin) 的 Swagger API 文档中未显示标头

Question

我正在使用 papsign/Ktor-OpenAPI-Generator 为 Ktor 应用程序生成 Swagger API 文档。我有一个 POST 端点，其中包含请求中的标头。完整代码如下：

fun main(args: Array<String>): Unit =
    io.ktor.server.netty.EngineMain.main(args)

@Suppress("unused")
fun Application.module() {
    
    install(OpenAPIGen) {
        info {
            version = "1.0.0"
            title = "Accelerated Earn"
            description = "Accelerated earn service provides extra earn."
            contact {
                name = "John Doe"
                email = "[email protected]"
            }
        }

        // describe the servers, add as many as you want
        server("/") {
            description = "This server"
        }

        replaceModule(DefaultSchemaNamer, object: SchemaNamer {
            val regex = Regex("[A-Za-z0-9_.]+")
            override fun get(type: KType): String {
                return type.toString().replace(regex) { it.value.split(".").last() }.replace(Regex(">|<|, "), "_")
            }
        })
    }
    
    // Configuring jackson serialization
    install(ContentNegotiation) {
        jackson {
            dateFormat = DateFormat.getDateTimeInstance()
        }
    }

    // Configuring swagger routes
    routing {
        get("/openapi.json") {
            call.respond(application.openAPIGen.api.serialize())
        }

        get("/") {
            call.respondRedirect("/swagger-ui/index.html?url=/openapi.json", true)
        }
    }
    
    demoFunction()
}

// Defining the DEMO tag
enum class Tags(override val description: String) : APITag {
    DEMO("This is a demo endpoint")
}

// Request is of type DemoClass, response is Boolean
fun Application.demoFunction() {
    apiRouting {
        tag(Tags.DEMO) {
            route("/demo") {
                post<Unit, Boolean, DemoClass>(
                    status(HttpStatusCode.OK),
                    info(
                        "Demo endpoint",
                        "This is a demo API"
                    ),
                    exampleResponse = true,
                    exampleRequest = DemoClass(name = "john doe", xyz = "some header")
                ) { _, request ->
                    respond(true)
                }
            }
        }
    }
}

@Request("Request")
data class DemoClass(
    @HeaderParam("Sample header")
    val xyz: String,
    @PathParam("Name")
    val name: String
)

在 DemoClass 中，我使用 @HeaderParam 注释将“xyz”属性表示为标头，并使用 @PathParam 注释将“name”表示为请求的参数。我预计“xyz”将在文档中显示为标头，但它显示为请求正文的一部分，并且没有提及有关标头的内容（如下图所示）

因此，同时制作请求时，我必须将标头放入请求正文中，而不是将其作为请求中的标头传递。有可能解决这个问题吗？我该怎么做？

Answer 1

发现错误了。 post函数的第一个参数是标题的类。这是更新后的代码：-

fun Application.demoFunction() {
    apiRouting {
        tag(Tags.DEMO) {
            route("/demo") {
                post<Headers, Boolean, DemoClass>(
                    status(HttpStatusCode.OK),
                    info(
                        "Demo endpoint",
                        "This is a demo API"
                    ),
                    exampleResponse = true,
                    exampleRequest = DemoClass(name = "john doe")
                ) { header, request ->
                    respond(true)
                }
            }
        }
    }
}

@Request("Request")
data class DemoClass(
    @PathParam("Name")
    val name: String
)

data class Headers(
    @HeaderParam("Sample Header")
    val xyz: String
)