如何在 Kotlin 中使用 Swagger @ApiResponses 注解？答案

【问题标题】：How to use Swagger @ApiResponses annotation in Kotlin?如何在 Kotlin 中使用 Swagger @ApiResponses 注解？
【发布时间】：2026-01-13 13:45:02
【问题描述】：

如何将以下 Swagger 注解从 Java 转换为 Kotlin？

 @ApiResponses(value = { @ApiResponse(code = 200, message = "Given admin user found"),
            @ApiResponse(code = 404, message = "..."),
            @ApiResponse(code = 500, message = "..."),
            @ApiResponse(code = 400, message = "..."),
            @ApiResponse(code = 412, message = "...") })

这不起作用：

@ApiResponses(value = listOf( 
        ApiResponse(code = 200, message = "..."),
        ApiResponse(code = 404, message = "..."),
        ApiResponse(code = 500, message = "..."),
        ApiResponse(code = 400, message = "..."),
        ApiResponse(code = 412, message = "...") ))

错误是：

类型推断失败。预期类型不匹配：推断类型为 List 但预期 ApiResponse

当我只使用一个@ApiResponse 而不是listOf() 时它可以工作，但我必须定义更多@ApiResponse(s)。

我使用 Swagger 2.5.0

【问题讨论】：

注解需要数组，而不是列表，因此请尝试使用arrayOf-函数而不是listOf()
现在出现错误：Type inference failed. Expected type mismatch: inferred type is Array<ApiResponse> but ApiResponse was expected
是的，这很奇怪。我很想说这可能是 Kotlin 中的一个错误
刚刚试过，实际上你需要完全省略value = listOf 部分，只需将各个参数放在顶层即可。当从 Kotlin 调用时，似乎 kotlin 将一个数组 value 转换为可变参数。
查看我对 Kotlin 语言参考中涵盖此内容的部分的回答以及应该为您工作的代码示例

标签： java annotations kotlin swagger

【解决方案1】：

对于 Swagger 3，这是要走的路：

 @ApiResponses(value = [
    ApiResponse(responseCode = "200", description = "...", content = [
        (Content(mediaType = "application/json", array = (
        ArraySchema(schema = Schema(implementation = DataModel::class)))))]),
    ApiResponse(responseCode = "400", description = "...", content = [Content()]),
    ApiResponse(responseCode = "404", description = "...", content = [Content()])]
    )

此 sn-p 还包括 @Content、@ArraySchema 和 @Schema 注释示例。

【讨论】：

【解决方案2】：

如the Kotlin Language Reference中所述：

如果 Java 中 [annotation] 的 value 参数具有数组类型，则它在 Kotlin 中成为 vararg 参数

所以，为了让你的例子工作，你需要这样说：

@ApiResponses(
    ApiResponse(code = 200, message = "..."),
    ApiResponse(code = 404, message = "..."),
    ApiResponse(code = 500, message = "..."),
    ApiResponse(code = 400, message = "..."),
    ApiResponse(code = 412, message = "...")
)

【讨论】：