SpringFox迁SpringDoc：Swagger 2.x中@ApiResponse的response替代方案

在SpringDoc（基于OpenAPI 3.0）中，Swagger 1.5的@ApiResponse里的response属性需要通过**@ApiResponse + @Content + @Schema**的组合来替代，核心是通过content字段指定响应的媒体类型和对应的实体类。

原代码（Swagger 1.5） #

@ApiResponses(value = [ApiResponse(code = 200, message = "Successful", response = MyResponse::class)])

替代代码（SpringDoc OpenAPI 3.0） #

// 注意引入的是OpenAPI的注解包
import io.swagger.v3.oas.annotations.responses.ApiResponse
import io.swagger.v3.oas.annotations.responses.ApiResponses
import io.swagger.v3.oas.annotations.media.Content
import io.swagger.v3.oas.annotations.media.Schema

@ApiResponses(value = [
    ApiResponse(
        responseCode = "200",
        description = "Successful",
        content = [Content(
            mediaType = "application/json",
            schema = Schema(implementation = MyResponse::class)
        )]
    )
])

关键说明 #

• 注解包路径变更：原io.swagger.annotations.ApiResponse替换为io.swagger.v3.oas.annotations.responses.ApiResponse
• 参数对应关系：code → responseCode，message → description
• 响应类型指定：通过content数组中的Schema(implementation = Xxx::class)实现原response属性的功能，同时可以指定mediaType明确响应的格式（如application/json、application/xml等）
• 自动推断优化：如果接口方法的返回值直接是MyResponse，SpringDoc可以自动识别返回类型，此时可省略显式的schema配置；但针对异常响应、统一包装类等场景，仍需要显式配置。

内容的提问来源于stack exchange，提问作者newLearner