Headers 未在 Ktor API (Kotlin) 的 Swagger API 文档中显示

Question

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

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 = "johndoe@gmail.com"
            }
        }

        // 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”属性表示为 header，并使用 @PathParam 注释将“name”表示为请求的参数。我希望“xyz”在文档中显示为 header，但它显示为请求 body 的一部分，并且没有提及 headers（如图所示在下图中）

因此，在发出请求时，我必须将 header 放入请求 body 中，而不是将其作为 header 传递到请求中。有可能解决这个问题吗？我该怎么做？

Answer 1

发现错误。 post函数的第一个参数是header的class。这是更新后的代码：-

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
)

Headers 未在 Ktor API (Kotlin) 的 Swagger API 文档中显示

Headers are not being shown in Swagger API documentation for Ktor API (Kotlin)

swagger

swagger-ui

openapi

ktor